Skip to content

Commit 2b557f4

Browse files
committed
[doc] add documentation on the documentation setup
1 parent c237049 commit 2b557f4

File tree

2 files changed

+39
-0
lines changed

2 files changed

+39
-0
lines changed

doc/developer-guide/documentation.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
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.

doc/index.md

+8
Original file line numberDiff line numberDiff line change
@@ -28,4 +28,12 @@ Publications <publications>
2828
contributing
2929
Using Ginkgo <using-ginkgo>
3030
API <_doxygen/html/index.html#https://>
31+
:::
32+
33+
:::{toctree}
34+
:hidden:
35+
:maxdepth: 2
36+
:caption: Developer Guide:
37+
38+
developer-guide/documentation
3139
:::

0 commit comments

Comments
 (0)