|
| 1 | +# Documentation Setup |
| 2 | + |
| 3 | +The documentation for Ginkgo is set up using |
| 4 | + |
| 5 | +- [Sphinx](https://www.sphinx-doc.org/) |
| 6 | +- [Doxygen](https://www.doxygen.nl/) |
| 7 | + |
| 8 | +Doxygen is used *only* for documenting the API through comments in the source code. |
| 9 | +No explicit Doxygen file (i.e. a file with only Doxygen content) shall be written. |
| 10 | +The `@cmd` syntax is used, where `cmd` is any valid doxygen command, see the list [here](https://www.doxygen.nl/manual/commands.html) for reference. |
| 11 | + |
| 12 | +Any other documentation is done via Sphinx. |
| 13 | +This includes the tutorial, how-to, and explanation aspects of the [diataxis](https://diataxis.fr/) approach. |
| 14 | +The [MyST](https://myst-parser.readthedocs.io) extension is used to allow markdown files as Sphinx input. |
| 15 | +Only markdown files shall be written for the Sphinx documentation. |
| 16 | +Admonitions shall be added with the `:::` syntax. |
| 17 | +The triple \` is reserved for code blocks. |
| 18 | + |
| 19 | +A connection from Sphinx to doxygen is established via [doxylink](https://github.com/sphinx-contrib/doxylink). |
| 20 | +With this, it is possible to reference the doxygen documentation by using the syntax |
| 21 | +```md |
| 22 | +{doxy}`gko::matrix::Dense` |
| 23 | +``` |
| 24 | +In the other direction, only the main page for the Sphinx documentation is available through doxygen. |
| 25 | +It is directly added to the `DoxygenLayout.xml` as a relative link. |
| 26 | + |
| 27 | +The connections between Sphinx and doxygen rely on correctly set output directories for both. |
| 28 | +The Sphinx output dir is the main one, and the doxygen output dir is defined relative to that. |
| 29 | +The Sphinx output dir is set to `SPHINX_OUTPUT_DIR=$CMAKE_BINARY_DIR/doc/html` and the doxygen output *has* to be put under `SPHINX_OUTPUT_DIR/_doxygen`. |
| 30 | +There will be an automatically generated subdir `html` of `_doxygen`. |
| 31 | +As the documentation setup uses relative path between doxygen and sphinx, messing up the path will lead to broken references. |
0 commit comments