Contributing to the Documentation

This documentation is built with Doxygen from Markdown source pages, sharing the same pipeline as the TRUST documentation. This page explains how to add or edit content.

Where the pages live

All hand-written narrative pages live under docs/content/, organised as a tree of Doxygen pages. Each .md file declares itself with @page <ID> <Title> and is attached to the tree by a parent page using @subpage <ID>. The root is docs/main_page.md, which uses the special @mainpage directive (it is the only content page kept at docs/ rather than under docs/content/).

Documentation layout

The top-level structure mirrors the TRUST documentation, but is thinner: TrioCFD-specific content lives here, and generic platform content is left to the TRUST documentation. New pages should be placed in the section that matches their audience and purpose:

Location	What goes there
content/quick_start.md	Getting started: building, sourcing the environment, running a first case.
content/user_guide/howto/	Task-oriented "how to write a data file" guides (define a mesh, set up a case, …).
content/user_guide/physical_models/	The physics of the models (turbulence, multiphase, FSI, sensitivity): equations, closures, best practices.
content/user_guide/numerical_methods/	TrioCFD-specific numerical methods; defer generic schemes to TRUST.
content/tutorials/	Step-by-step user tutorials starting from an existing test case.
content/implementation/	How TrioCFD is implemented: code/module architecture, discretization as coded, algorithmic details. Reference material for developers and users.
content/dev_corner/	Developer workflow and contributing guidelines (git, testing, this page) — not the implementation itself.
content/references.md + references.bib	Bibliography (consolidated .bib; cited with @cite).
content/figures/	Images referenced by the pages (IMAGE_PATH points here).

If you are unsure whether something is "physical model", "numerical method" or "implementation": keep a coherent exposition together where its author placed it and add a cross-link (@ref) rather than splitting it across sections. The C++ class/namespace API is generated automatically from the source and appears in the C++ API sidebar tab — you do not write it by hand.

Writing pages

The most important rules:

• Put new content pages under content/ (the only exception is main_page.md).
• **@page <ID> <Title> is rendered as the single top-level (#) title of the page.** Every other heading in the page must be ## (a second-level heading) or deeper — never a second #, otherwise the left navtree becomes messy. (This point is easy to miss: it is not spelled out explicitly in the TRUST guide, so keep it in mind.)
• Attach every page to the tree from its parent via @subpage <ID>; @page IDs must be unique across the whole documentation.
• Do not add @ingroup to pages that are part of the @subpage tree (in recent Doxygen it conflicts with @subpage and can silently drop the page from the navtree).
• On main_page.md only: do not use ## headings while @subpage links are present (Doxygen mis-nests them in the navtree); use raw <h2>…</h2> HTML tags there instead.
• Math uses Doxygen formula commands (\f$…\f$ inline, \f[…\f] display), not bare $…$ (see the Math section below).
• Figures go under content/figures/ and are referenced as figures/<name> (e.g. ). Convert .pdf/.eps source figures to .png/.svg.
• TikZ / LaTeX figures are kept as source under content/figures/src/ (one self-contained standalone .tex per figure) and committed as the rendered figures/<name>.svg alongside. The doc build has no LaTeX dependency — these are not rebuilt by make. After editing a source, regenerate and re-commit the SVG with content/figures/src/build.sh (needs pdflatex + pdftocairo); see the header of that script for details.
• Cross-references: link to another page with @ref <PageID> (optionally @ref <PageID> "link text"); cite the bibliography with @cite <key> (keys from content/references.bib); link to TRUST docs with absolute https://…readthedocs.io/… URLs.
• All pages are written in English.

These rules complement the shared TRUST authoring guide, whose full version lives in the TRUST docs tree:

• $TRUST_ROOT/docs/README.md — the documentation build system and structure.
• $TRUST_ROOT/docs/How_to_write_doc.md — the author-facing guide (declaring pages, wiring them into the navtree).

Math

Equations are written with Doxygen's formula commands, which Doxygen hands to MathJax for rendering. There is no Markdown $…$ math in this pipeline.

• Inline: \f$ … \f$, e.g. the turbulent viscosity \f$\nu_t = C_\mu \overline{k}^2/\overline{\epsilon}\f$.
• Display (block): \f[ … \f] on its own lines:

  \f[
  \frac{\partial \rho}{\partial t} + \boldsymbol{\nabla}\cdot(\rho\mathbf{u}) = 0
  \f]

• Multi-line / aligned display: put a LaTeX environment inside \f[ … \f]:

  \f[
  \begin{aligned}
  \boldsymbol{\nabla}\cdot\mathbf{u} &= 0,\\
  \rho_0\,\partial_t\mathbf{u} + \rho_0(\mathbf{u}\cdot\boldsymbol{\nabla})\mathbf{u}
    &= -\boldsymbol{\nabla} p + \eta_0\boldsymbol{\nabla}^2\mathbf{u}.
  \end{aligned}
  \f]

The LaTeX inside (\frac, \nabla, \mathbf, \begin{aligned}, \begin{cases}, …) is rendered by MathJax, so the usual amsmath constructs work.

Warning

Do not use bare $…$ or $$…$$. Doxygen does not treat them as math: it parses the backslash sequences inside (\frac, \rho, …) as Doxygen commands, which floods the build with "Found unknown command" warnings and breaks the rendering. For the same reason, keep formula commands out of places Doxygen parses specially — in particular, image alt-text () must be plain words, not \f$…\f$.

Building the documentation

The documentation is built independently of the TrioCFD compilation:

cd docs
make

The resulting HTML is written to docs/build/html/. See $TRUST_ROOT/docs/README.md for the available targets.

Viewing the built documentation

Serve the output over HTTP — do not open the files directly via file://. Browsers treat a file:// page as a "null origin" and block the XMLHttpRequests that MathJax uses to fetch its math data, so equations do not render (you will see blocked by CORS policy errors in the browser console). The dark-mode preference (stored in localStorage) is also unreliable over file://. Start a local web server and open the http:// URL instead:

python3 -m http.server --directory build/html 8000
# then open http://localhost:8000/

If the build is on a remote machine, forward the port first from your local machine, e.g. ssh -L 8000:127.0.0.1:8000 <host>, then open http://localhost:8000/. The deployed documentation is served over HTTP, so this only affects local previews.

The keyword reference (trustify)

The Keywords Reference Manual is generated automatically from the C++ source code by the trustify tool (run by make trustify_doc, part of make); it is not written by hand. trustify parses special // XD comments embedded in the C++ sources — at each class derived from Objet_U that can be read as a keyword in a .data file, and after each parameter added with param.ajouter — and emits the keyword reference pages. To document a keyword, edit the corresponding // XD / // XD_ADD_P comment in the .cpp source, not the generated Markdown.

The full // XD tag syntax (parameter types, flags, …) and the trustify workflow are documented on the TRUST side, since trustify is shared between TRUST and TrioCFD. The new Doxygen TRUST documentation is not online yet; in the meantime:

• TRUST documentation on ReadTheDocs: https://cea-trust-platform.readthedocs.io/en — the keyword-documentation guidance is found under the Developer Corner in the navigation tree (with the generated keyword list under the user guide's reference section);
• in the source tree, the trustify guides are at $TRUST_ROOT/Outils/trustify/doc/README_user.md (authoring) and $TRUST_ROOT/Outils/trustify/doc/README_dev.md (internals).