Hi there 👋 and welcome to the TrioCFD Documentation project page! The documentation is devoted to describe the TrioCFD fluid dynamics code.
The documentation is built with the the open source Sphinx and Doxygen projects.
git clone [email protected]:cea-trust-platform/triocfd-documentation.git
python -m venv .venv
source .venv/bin/activate
pip install -r doc/requirements.txt
cd doc
make htmlUse your web browser to open the index file located at build/html/index.html. When rebuilding after modifications, the browser may cache the files and refuse to update the pages. In this case, use make clean html.
To produce a pdf, one must have latexmk installed and run make latexpdf.
For vscode users, there are also tasks defined: configure that create and source venv and install dependencies, build (does make html) and open that directly opens the result in your webbrowser.
Two formats can be used in Sphinx, reStructuredText and Markdown. The complete markdown syntax is described by the MyST Syntaxe Guide.
To write math, the dollar separated syntax from LaTeX works as well as environment like \begin{align}. One can also write in markdown without latex
{math}`k-\varepsilon`
to produce \begin{align}.
The bibliography is managed by a bibtex sphinx module. In markdown, one must use {cite:t} to produce Author et al. [key].
The Doxygen documentation of TRUST and TrioCFD is included in this doc. Documentation of a specific class or function can be cited using the syntax given in the doxygen section. This is done with the external (self-developped) python package DoxygenToRST.
To ease the further development and testing of DoxygenToRST, a local version can be created and edited using make updateDoxygenToRST (in the source subdirectory). The first use of this makefile target will create the local copy and install it. After editing DoxygenToRST sources, it can be reinstalled with the same target (updateDoxygenToRST).
To shorten build time when editing DoxygenToRST, a test mode can be enabled by setting the env variable TEST_RST to 1. A common usage while developing will be:
TEST_RST=1 make updateDoxygenToRST clean htmlwhich will update the python package, create the rst files from Doxygen data (in test mode) and rebuild the html website all at once.
Test mode works by filtering the Doxygen files that will be included in the final website. A file named .doxygen_test_list must be present beside the conf.py file that contains patterns of class/file names that will be included in the test build. In this mode, there will be warning of missing references if the whole inheritance family of a class is not included. This mode is meant mostly to test the visual aspect of the resulting rst files.
The website is deployed on readthedocs, with the latest version here.
Build and deploy is triggered automatically from the github workflow that runs on pushes to master.
Build status is available here.
The website is also deployed on github-pages.
Build and deploy is triggered automatically when pushing on master branch, and can also be triggered manually (useful if only DoxygenToRST has changed for example).
Build status is available here.
The full build procedure and configuration is explained here.