Building the Docs

Offering documentation edits while using HDTree is incredibly helpful.

The automatically generated documentation from source code is usually more detailed and is done differently depending on the language being written, so that "API Reference" is kept in separate sites for each API. Manually written documentation is also separated by API, but are all written here and processed by mdbook.

Launching Local Version of Docs

After installing mdbook, you can use it to build and serve the doc website locally on your computer while you are writing documentation. It will then automatically refresh the website when it detects that files have changed.

Note: Some of the links in the mdbook point to the reference manuals that are generated differently in order to conform to language-specific standards, so without generating those manuals those links will be broken.

Reference Manuals

The different APIs have different methods of generating reference manuals from the comments in the code. Besides editing the manual documentation and having it processed by jekyll, these files are copied onto the gh-pages branch into a subdirectory so that they are not modified by jekyll but still hosted at the same website.

C++

The C++ reference is generated using doxygen and the doxygen-awesome theme. The theme is kept in a git submodule, so you will need to make sure the submodules are downloaded for the local version to be the same theme as the online version.

git submodule --update --init

After installing doxygen, it is expected to be run from the root of this repository.

doxygen cpp/docs/doxyfile

This produces the HTML doxumentation in the cpp/docs/html directory. You can view the HTML files generated by doxygen by opening them in your favorite browser. For example,

firefox cpp/docs/html/index.html