DocGuard is a lightweight, extensible Ruby gem that helps ensure your documentation remains accurate as your code evolves. It tracks source files referenced in documentation and warns when changes occur.

• Automatic File Tracking:
  Easily annotate your documentation files with the source code files they reference. DocGuard automatically detects which files your docs depend on, eliminating manual tracking.

• Digest Calculation & Change Detection:
  DocGuard computes SHA256 digests (hashes) of tracked files and compares them with previously stored digests to detect any changes. This helps identify when code changes may impact your documentation.

• Real-time Relevance Assessment:
  Quickly determine if your documentation is still relevant based on the current state of your code. Get instant feedback when your docs might be outdated.

• Clear and Actionable Reporting:
  Receive concise CLI reports highlighting which files caused potential documentation mismatches, helping you prioritize documentation updates.

• Fail-safe Exit Codes:
  Integrate DocGuard seamlessly into CI/CD pipelines, it exits with meaningful statuses:

  • 0 when docs are up to date,
  • 1 when documentation may be outdated,
  • 2 on unexpected errors.

• Flexible CLI (built on Thor):
  Easy-to-use commands to assess relevance and extend with future commands for recording or other workflows.

• Lightweight & Framework Agnostic:
  Works well in Rails projects but designed to be framework-independent and lightweight enough to fit any Ruby codebase.

• JSON-based Digest Storage:
  Stores digests in a human-readable JSON file, making it easy to audit or manage outside the tool if needed.

Install the gem and add to the application's Gemfile by executing:

bundle add doc_guard

If bundler is not being used to manage dependencies, install the gem by executing:

gem install doc_guard

or add this line to your application's Gemfile:

gem "doc_guard"

To enable DocGuard to track which source files your documentation depends on, add a special HTML comment in your markdown files (e.g., README.md or any .md files inside a docs/ folder).

Insert the following comment at the top (or anywhere relevant) in your markdown file:

<!-- doc_guard files: [app/models/user.rb, app/services/authenticator.rb] -->
Your amazing and very important documentation related to the user model and authentication service is here.

$ doc_guard record

This stores the current digests of referenced files in .doc_guard_digests.json.

$ doc_guard assess

Example output:

‼️ Documentation may be outdated!

📄 docs/user.md
- app/models/user.rb
- app/services/authenticator.rb

📄 docs/admin.md
- app/models/admin.rb

DocGuard can be configured in multiple flexible ways to suit different environments (e.g., local development, CI/CD pipelines, GitHub Actions).

Configuration values are resolved using the following priority:

1. CLI flags
2. Environment variables
3. YAML config file (.doc_guard.yml)
4. Internal defaults

Note: The config_file_path is used only to load other settings from a YAML file. It cannot itself be configured via YAML.

# .doc_guard.yml

documentation_path: custom_docs
digests_store_file_path: tmp/doc_guard_state.json

Note: Place this file in your project root.

This configuration approach supports usage in CI/CD pipelines, local development, or scripts, without any dependency on Rails or other frameworks.

The following features are being considered or are actively planned for future releases:

• External documentation integrations
  Support for syncing and validating documentation that lives outside the main codebase, e.g., Confluence, GitHub Wikis, or other remote documentation tools.

• Custom digest strategies
  Allow users to define custom strategies for calculating file "change relevance", e.g., ignore comments or whitespace, or weigh different parts of the code differently.

• AI-assisted relevance analysis
  In the future, integrate with AI systems to help assess whether documentation should be updated based on the semantic nature of recent code changes (e.g., if a developer introduces a new feature but forgets to update corresponding docs).

• Advanced code–documentation annotation system
  Improve how source code is linked to documentation, potentially with fine-grained annotations (e.g., per method, class, or even logic block), offering a more accurate mapping between code changes and relevant documentation sections.

Have an idea or need a feature? Feel free to open an issue or contribute!

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/patrickgramatowski/doc_guard. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the DocGuard project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.