Building the manual

  • cargo install —git https://github.com/immunant/mdBook.git —branch installable (May require —force if you already have mdbookinstalled. Requires custom changes to resolve symlinks, hopefully will bemerged into upstream soon)
  • mdbook build in the root source directory
  • The manual should now be available in the book subdirectory.[

Adding to the manual

  • Add a new Markdown file somewhere in the repository.
  • Edit manual/SUMMARY.md and add a link to the new file.Use a path relative to the repository root.
  • Add the new Markdown file to the git index (git add …)
  • Run scripts/link_manual.py from the root directory. This will create asymlink for the new file in the manual/ directory. This symlink should beadded to git as well.[

Generated docs

The manual/generator_dispatch.py script runs as an mdbook preprocessor andreplaces {{#generate GEN ARGS}} anywhere in the book with the outputof running generator GEN on ARGS. The set of available generators isdefined in generator_dispatch.py.

As one example, this is used in manual/c2rust-refactor/commands.md to replacethe {{#generate refactor_commands}} placeholder with auto-generateddocs for refactoring commands, by runningc2rust-refactor/doc/gen_command_docs.py.

API documentation for the Lua scripting interface is generated by calling ldoc .in the c2rust-refactor directory. This updates the c2rust-refactor/doc/scripting_api.htmlfile which we keep checked into source control and linked into the manual.