https://github.com/patrickgramatowski/doc_guard
A tool to track and assess the relevance of your documentation by linking docs with the actual source files they describe. Helps ensure your docs stay up-to-date with your codebase.
https://github.com/patrickgramatowski/doc_guard
doc-guard docguard documentation documentation-tool ruby ruby-gem up-to-date up-to-date-documentation
Last synced: 5 months ago
JSON representation
A tool to track and assess the relevance of your documentation by linking docs with the actual source files they describe. Helps ensure your docs stay up-to-date with your codebase.
- Host: GitHub
- URL: https://github.com/patrickgramatowski/doc_guard
- Owner: patrickgramatowski
- License: mit
- Created: 2025-06-28T10:41:17.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-07-03T18:55:05.000Z (12 months ago)
- Last Synced: 2025-07-04T07:41:08.472Z (12 months ago)
- Topics: doc-guard, docguard, documentation, documentation-tool, ruby, ruby-gem, up-to-date, up-to-date-documentation
- Language: Ruby
- Homepage:
- Size: 334 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
---
### 🛡️ 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](https://github.com/rails/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:
```bash
bundle add doc_guard
```
If bundler is not being used to manage dependencies, install the gem by executing:
```bash
gem install doc_guard
```
or add this line to your application's Gemfile:
```ruby
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:
```md
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 💾
```bash
$ doc_guard record
```
This stores the current digests of referenced files in `.doc_guard_digests.json.`
#### 3. Assess documentation relevance 🚦
```bash
$ doc_guard assess
```
Example output:
```bash
‼️ 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
```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.
### 🛣️ 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](https://github.com/patrickgramatowski/doc_guard/issues) 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](https://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](https://github.com/patrickgramatowski/doc_guard/blob/master/CODE_OF_CONDUCT.md).
### 📄 License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
### 📜 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](https://github.com/patrickgramatowski/doc_guard/blob/master/CODE_OF_CONDUCT.md).