Documentation¶
Most readers love documentation, its creators hate it.
Unfortunately, nobody can look inside your head and have the same ingenious thoughts as you do. To ensure your thoughts also reach the afterworld, please document your stuff reasonably!
The documentation is split up in two parts: static and dynamic docs,
Static Docs¶
Dedicated documentation files reside in the doc/ directory, where this
readme file lies in as well. You can find ideas, milestones, planning and
workflow descriptions etc in here.
A good entry point may be the file doc/project_structure. it roughly explains where to find what code in the project.
If you made any relevant discoveries or gained insights that help others understand any part of the project:
Create a file and write down your thoughts
Ideally, use markdown syntax, alternatively plain text
Submit your contribution (pull request) so we can include it in the official repository
This ensures newcomers can start developing easily
Dynamic Docs¶
This type of documentation is written inside code files:
C++ methods and classes are documented in their header files
Python methods and classes are documented via docstrings
Due to potential documentation laziness, the above statements might be out-right fabrications.
Doc Generation¶
Dynamic documentation can be auto-generated from source documentation using doxygen.
after calling ./configure, you can invoke
make doc
to create doxygen html and LaTeX files.
After creation, view them in a browser by
$BROWSER bin/doc/html/index.html
or, if you want to create LaTeX documents, run
make -C bin/doc/latex/ pdf
$PDFVIEWER bin/doc/latex/refman.pdf
Webdoc Generation¶
Install Dependencies¶
You will need nearly all the basic dependencies as if you would build openage itself. Namely cmake, make, python3, nyan, etc. Make sure you have these.
Furthermore you’ll need the following:
sudo apt update
sudo apt install doxygen graphwiz
python -m pip install --upgrade pip
pip install -U sphinx doxypypy recommonmark autodoc breathe graphviz sphinx-markdown-tables sphinx-rtd-theme sphinxcontrib-moderncmakedomain
Building Documentation¶
Dynamic documentation for webhosting-purposes can be auto-generated from source documentation using doxygen in the first stage with sphinx and breathe in the second stage.
after calling ./configure --build-webdoc, you can invoke the complete building process with
make webdoc
Doxygen is taking care of the documentation of the C++ parts. Although Doxypypy will take care of the Python parts and the rearrangement of the Markdown doc parts, we use Sphinx in combination with Breathe to generate a clean documentation suitable to our needs and easily hostable in the web. After that make-command you will find the openage-docs folder one directory level over your cloned repository.
HINT: If you need to regenerate just the second stage with Sphinx you can call make webdoc-sphinx.