Expand description
§Rdocs: Code Documentation Made Simple
§Introduction
When working on open-source projects or internal projects, creating effective documentation is essential. As a developer, I often faced the challenge of generating and maintaining comprehensive project documentation. The example below demonstrates various types of documentation I’ve included:
- Examples showcasing how to use the application configuration.
- A README guide illustrating the usage of my CLI.
- Code snippets demonstrating the usage of my library in different scenarios.
However, a common issue is ensuring that the examples provided in the documentation remain accurate and up-to-date. What if the example code changes? What if there’s a typo in the documented code? How can we ensure that the examples always reflect the current state of the codebase?
Imagine a tool that allows you to extract code snippets, ensuring they are
not only reliable but also executable. What if you could easily incorporate
pieces of code that are known to work or leverage tested examples from
languages like Rust, which use Doctest? This tool is designed to address
these concerns.
§Goal
My objectives are as follows:
- Alignment with Code: Ensure documentation consistently aligns with the codebase.
- CI Validation: Incorporate validation into Continuous Integration to ensure documentation validity.
- User-Friendly: Prioritize ease of use for all stakeholders.
- Minimal Dependencies: Enable documentation validity even without external tool dependencies.
§Installation
Cargo install:
cargo install rdocs
GitHub Releases: https://github.com/kaplanelad/rdocs/releases/latest
Modules§
- A module for handling command line exits with custom messages and exit codes.
- A module for collecting files based on include and exclude patterns.
- A module for defining custom error types and result aliases for parsing
- A module for exporting content
- A module for parsing and extracting content based on patterns from files.
- A module for defining patterns used in parsing and extracting content.
- A module for performing content replacement in files based on specified patterns.