https://github.com/jakestanger/rust-bindocs
A tool to assist writing documentation for Rust binaries.
https://github.com/jakestanger/rust-bindocs
binary cli documentation generator markdown rust
Last synced: about 1 month ago
JSON representation
A tool to assist writing documentation for Rust binaries.
- Host: GitHub
- URL: https://github.com/jakestanger/rust-bindocs
- Owner: JakeStanger
- License: mit
- Created: 2023-07-29T20:26:53.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2023-07-29T21:06:56.000Z (almost 3 years ago)
- Last Synced: 2025-02-26T22:37:45.542Z (over 1 year ago)
- Topics: binary, cli, documentation, generator, markdown, rust
- Language: Rust
- Homepage: https://crates.io/crates/bindocs
- Size: 31.3 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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`
[crate](https://crates.io/crates/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 `/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 `/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:
```rust
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:
```markdown
# 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:
````markdown
## 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](https://github.com/jakestanger/corn)
after the path to the type, before the closing brace.
For example, to change the heading depth:
```markdown
<% 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.