---

🛡️ Keep your documentation up-to-date with your code

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.

---

🚀 Features

• 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.

💿 Installation

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"

⚙️ Usage

1. Annotate Documentation with Tracked Files 📝

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).

How to annotate:

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.

2. Record the current state of the relationship between your documentation and your code 💾

$ doc_guard record

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

3. Assess documentation relevance 🚦

$ 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

🔧 Configuration

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

🗂️ Available Configuration Options

Setting	CLI Flag	ENV Variable	YAML Config Key	Default Value
Documentation path	--documentation-path	DOC_GUARD_DOCUMENTATION_PATH	documentation_path	"docs"
Digests store file path	--digests-store-file-path	DOC_GUARD_DIGESTS_STORE_FILE_PATH	digests_store_file_path	".doc_guard_digests.json"
Config file path (for YAML)	--config-file-path	DOC_GUARD_CONFIG_FILE_PATH	(Not loaded from YAML)	".doc_guard.yml"

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

📁 Config File Example

# .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.

🛣️ Roadmap

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!

🧑‍💻 Development

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.

🤝 Contributing

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.

📄 License

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

📜 Code of Conduct

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