How to doc

Effective documentation is crucial in various fields, including software development. It serves as a vital communication tool, conveying important information to end-users, developers and team members. Well-documented processes can streamline workflows, enhance productivity, and ensure consistency and accuracy across projects.

Amethyst tries to be a well documented codebase. We use a mix of Sphinx with breathe and combined information from Doxygen for our documentation.

Doxygen is a documentation generator tool that is widely used in the software development to generate documentation for software projects. It sadly isn’t the newest piece of software and the websites it produces aren’t the best looking, that is why we decided to use sphinx and doxygen together.

Hint

To learn more about how to document your C++ code using doxygen comments in your headers, look at the doxygen Amethyst docs

Sphinx is an open-source documentation generation tool used primarily for creating high-quality documentation for software projects, but it can be used for any type of documentation. It was originally created for the Python programming language, but it supports multiple programming languages and document formats.

We can write simple documentation for sphinx using RST (reStructuredText).

Hint

To learn more about how to write sphinx docs using rst, look at the sphinx Amethyst docs

Doxygen can’t communicate with sphinx directly, that is why we use a bridge called breathe.

Breathe uses xml files generated by doxygen to gather the information needed it generates rst files from the xml data using breathe-apidoc.

These rst files are then used by sphinx to generate html. We use a special sphinx theme called Awesome Sphinx Theme as well, to improve the look of our documentation.

Note

If you want to locally try out sphinx and doxygen with breathe, then follow the setup guide.