# 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/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:

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