1 unstable release
0.1.0 | Jul 29, 2023 |
---|
#13 in #documentation-tool
38KB
904 lines
Rust Bindocs
A tool to assist writing documentation for Rust binaries.
Rustdoc is a brilliant tool, but it's only really suited to libraries. Documenting applications can be a pain, because you often need to reference types from the code, but don't want to include all the internal information or require end-users to look at code docs. The alternative is writing everything by hand, but keeping that in sync with code changes can be a pain, and it is easy to make mistakes.
This tool is designed to simplify that process by providing a basic templating engine that can generate documentation straight from your source code, optimised for end-users, and inlined in your existing docs.
Existing Rustdoc comments are fully supported, and the contained markdown is seemingly integrated into your document.
⚠️ The tool is currently in its infancy. Only Markdown output is supported, and expect bugs.
Installation
cargo install bindocs
Usage
The crate includes a CLI. Point it at the root of a crate, optionally specify the documentation input/output directories, and your docs will be rendered out.
Args
project_path
Type:
PathBuf
Path to the crate root. Defaults to current dir.
docs_path
Type:
PathBuf?
Path to the document templates(s).
This can be a file name for a single file, or a directory for multiple.
Defaults to <project_path>/docs
.
output_path
Type:
PathBuf?
Path to output the rendered doc(s).
This can be a file name for a single file, or directory for multiple.
Defaults to <project_path>/target/bindoc
.
Inside your input markdown, use <% template_blocks %>
to denote where types should automatically be injected.
You can inject any struct or enum owned by your crate.
For example, if you have a config
module containing a MyConfig
struct:
struct MyConfig {
/// Enables foo mode.
foo: bool,
/// Specifies the `bar` value to use.
///
/// # Example
///
/// ```json
/// { "bar" = "baz" }
/// ```
bar: String,
}
You can inject it into your documentation as follows:
# My docs page
Lorem ipsum dolar sit amet.
<% config::AppConfig %>
Ornare lectus sit amet est placerat in egestas.
This will produce an output similar to the below:
## MyConfig
### foo
> Type: `bool`
Enables foo mode.
### bar
> Type: `String`
Specifies the `bar` value to use.
#### Example
```json
{ "bar": "baz" }
```
✅ If the type is uniquely named within your project, you can omit the path (ie just
AppConfig
) and bindocs will resolve it still.
Configuring injections
Each injection can be individually configured using Corn after the path to the type, before the closing brace.
For example, to change the heading depth:
<% config::AppConfig { depth = 3 } %>
Injection replace options
header
Type:
bool
Whether to include the element header. Defaults to true.
depth
Type:
usize
The current heading depth, starting at 0
.
Headings will be placed at one more than the current depth.
For example, if the next heading should be ## h2
, use a depth of 1
.
Contributing
Contributions are welcome!
If you find any issues, please open a bug report.
If you have a feature request, please open an issue first to allow it to be discussed. More options and render formats are more than likely to be accepted.
Dependencies
~8–17MB
~219K SLoC