File List
Not logged in

The union of all files from all check-ins in directory wiki_references/2017/software/Rust/src_from_GitHub/the_repository_clones/rust/src/tools/cargo/src/doc   [history]


Cargo documentation

This directory contains Cargo's documentation. There are two parts, The Cargo Book which is built with mdbook and the man pages, which are built with Asciidoctor. The man pages are also included in The Cargo Book as HTML.

Building the book

Building the book requires mdBook. To get it:

$ cargo install mdbook

To build the book:

$ mdbook build

mdbook provides a variety of different commands and options to help you work on the book:

The book contents are driven by the SUMMARY.md file, and every file must be linked there.

Building the man pages

Building the man pages requires Asciidoctor. See the linked page for installation instructions. It also requires the make build tool and ruby.

The source files are located in the src/doc/man directory. The Makefile is used to rebuild the man pages. It outputs the man pages into src/etc/man and the HTML versions into src/doc/man/generated. The Cargo Book has some markdown stub files in src/doc/src/commands which load the generated HTML files.

To build the man pages, run make in the src/doc directory:

$ make

The build script uses a few Asciidoctor extensions. See asciidoc-extension.rb for details.

Contributing

We'd love your help with improving the documentation! Please feel free to open issues about anything, and send in PRs for things you'd like to fix or change. If your change is large, please open an issue first, so we can make sure that it's something we'd accept before you go through the work of getting a PR together.