Writing Documentation for RAYX¶

This site is build from Markdown files inside the docs directory, based on the configuration in mkdocs.yml. The page structure is defined in docs/.nav.yml, see mkdocs-awesome-nav.

The API documentation is built using Doxygen together with MkDoxy.

Versioning of the site is implemented using Mike. The CI takes care of the necessary steps, but it is also possible to manually add, update or remove versions as needed.

Local Development Setup¶

To build and test the documentation locally, install the python docs dependencies from pyproject.toml as well as doxygen (for the API documentation).

With uv setting up a virtual environment and installing locked dependencies is done with:

uv sync --locked --group docs

Then either activate the virtual environment or prefix commands with uv run.

Start the live-reloading docs server locally with:

mkdocs serve --livereload

Temporarily disabling MkDoxy¶

When working on documentation the local server takes some time to check and link the API documentation, even though the Doxygen output is cached to a .mkdoxy dir and only regenerated when necessary. MkDoxy can be temporarily disabled with the environment variable ENABLE_MKDOXY

ENABLE_MKDOXY=false mkdocs serve

This is useful when writing documentation pages that don't use the API docs and you want to check the resulting page regularly, e.g. when using a lot of math.

Markup¶

Here is a quick overview of some of the available Markdown syntax. You can have a look at the source of this file too. This is also possible directly in the browser for every page on this site. At the top there is a link to view the source.

For a more thorough documentation have a look at the Material for MkDocs reference.

Linking to other pages¶

Using markdown links relative to the current file (not the current page) this syntax is simply:

[Home](index.md)

Home

Images¶

There are some additional settings available for images that are not part of core markdown, like sizing and captions, see Image Options.

RAYX Logo with a width of 300px

Lists¶

Unordered
List
- Nested levels need 4 spaces

Ordered
List
1. Next Level
2. Hi mom

Math¶

\[ \cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k} \]

Emojis¶

🏳️‍🌈

Source code¶

Bragg angle computation from Crystal.h
/// @brief Computes the bragg angle
/// @param energy photonenergy of the ray
/// @param d lattice spacing*2
/// @param order Diffraction order
/// @return the bragg angle theta (rad)
RAYX_FN_ACC double getBraggAngle(double energy, double dSpacing2) {
    int order = 1;
    double wavelength = hvlam(energy);
    double theta_factor = (order * wavelength) / dSpacing2; // (1)!

    // Check for physical validity
    if (theta_factor > 1.0) {
        return -1.0;  // No reflection possible
    }

    double theta = asin(theta_factor);  // In radians
    return theta;
}

SCIENCE! With inline SCIENCE
Some Bragg related math: $n \lambda = 2 d \sin \theta$

Or as a separate block: $$ n \lambda = 2 d \sin \theta $$

Admonitions¶

Admonitions

Admonitions are great!

Collapsible example

Collapsible Admonitions are nice too.

Bragg angle computation from Crystal.h

/// @brief Computes the bragg angle
/// @param energy photonenergy of the ray
/// @param d lattice spacing*2
/// @param order Diffraction order
/// @return the bragg angle theta (rad)
RAYX_FN_ACC double getBraggAngle(double energy, double dSpacing2) {
    int order = 1;
    double wavelength = hvlam(energy);
    double theta_factor = (order * wavelength) / dSpacing2; // (1)!

    // Check for physical validity
    if (theta_factor > 1.0) {
        return -1.0;  // No reflection possible
    }

    double theta = asin(theta_factor);  // In radians
    return theta;
}

SCIENCE! With inline code

Diagrams¶

graph LR
  A[Start] --> B{Failure?};
  B -->|Yes| C[Investigate...];
  C --> D[Debug];
  D --> B;
  B ---->|No| E[Success!];

Inline API documentation with MkDoxy¶

This plugin uses Doxygen to generate markdown files from the code comments. You can include parts of the API documentation as Snippets into the written guides using a tag syntax.

Tag SyntaxResulting Snippet

::: doxy.rayxCore.class.method
name: rayx::BeamlineNode
method: glm::mat4 getOrientation()

function getOrientation¶

Gets the local orientation (rotation/transform) of this node.

virtual glm::dmat4 rayx::BeamlineNode::getOrientation () const = 0

Each node may have its own transform relative to its parent.

Returns:

A 4x4 matrix (dmat4) representing the local orientation.

If there is an error inside the MkDoxy Tag it generates a helpful block with the error, available tags and the corresponding snippet. For example using the tag without any config shows the available projects.