2 unstable releases
Uses old Rust 2015
0.2.0 | Aug 22, 2019 |
---|---|
0.1.0 | Nov 13, 2016 |
#545 in Cargo plugins
10KB
147 lines
cargo external-doc
This tool allows you to add markdown files to your crate's documentation generated with rustdoc.
The documentation generated by rustdoc
is meant for code and API references,
and does not offer a nice way to add long form documentation. This tool
will fix that until rustlang/cargo#739
is implemented.
Installation
cargo external-doc
is installed via cargo install
:
$ cargo install cargo-external-doc
Usage
Put your articles written in markdown in the doc/
subfolder of your
project (see nom for an example).
rustdoc
requires that the files are prefixed with a title like this:
% Your title here
Now, run cargo build
then cargo external-doc
. This tool will:
- call
cargo doc
- test the code examples in the files from
doc/
- generate html files consistent with
rustdoc
's templates and put them intarget/doc/your_crate
Your other documentation files can reference it by relative URL, like this for a doc/guide.md
file:
cf the [guide](guide.html)
Example
In nom, you can see:
- the
doc/
folder - the online reference with links to articles
- the links in
src/lib.rs
- the parser writing article and its source
Caveats
This tool is a temporary solution, until something better is
integrated in cargo doc
.
It does not support overriding values like the target path.
It relies on the target/debug/libyourcrate.rlib
file existing.
It does not check for invalid links.
It is not configurable.
It fits a need I have for nom, and it might
not fit what you want. I'm open to modification ideas and patches, but I'd
prefer to see it implemented correctly in cargo doc
instead.
Dependencies
~4–12MB
~115K SLoC