Editing the Etterna Documentation Site

The Etterna documentation site you’re reading right now is automatically generated by a GitHub Actions workflow.

The GHA workflow

The GitHub actions workflow actually generating this entire website can be viewed in the Etterna repository.

The workflow runs a series of steps to achieve three primary goals:

1. Rendering the markdown files present in the repository into nicely formatted html.

   This is done using Jekyll alongside a custom theme; details can be seen here

   We do this because raw Markdown is … not pretty to look at.

2. Automatically generating documentation for Etterna’s C++.

   This is done using Doxygen; details can be seen here

3. Automatically generating documentation for Etterna’s Lua.

   This is done using LDoc; details can be seen here

Jekyll and the Site Theme

Markdown files are converted into html using a GHA workflow.

To apply styling making the site actually look nice (and granting functionality like the nav bar and search bar), we use the theme just-the-docs.

The site can be configured at various levels:

Jekyll itself can be configured by editing the file Docs/_config.yml.
Details of what configuration options are available can be seen in Jekyll’s documentation.
This configuration is used for big-scale things like what files should be included/excluded from the rendering and what theme is being used.

The particular theme we’re using, just-the-docs, also has a substantial amount of configuration options available.
The full list can be seen in their documentation.
Some configuration of just-the-docs is done by editing Docs/_config.yml, some by adding yml to the top of markdown files (e.g. as seen in Keymaps_ini_format.md), and some by editing other configuration files such as the CSS-styling file Docs/_sass/color_schemes/etterna.scss

C++ Documentation and Doxygen

C++ documentation is automatically generated from C++ source files using Doxygen.
The configuration file used by doxygen is generated via Etterna’s CMake operating on the file Docs/Doxyfile.in

Various configuration options can be changed for Doxygen to modify its produced output; a list can be seen in Doxygen’s documentation.

Lua Documentation and LDoc

Lua documentation is automatically generated from Lua source files and written documentation using LDoc.
The configuration file used by LDoc is generated via Etterna’s CMake operating on the file Docs/LDoc.in

Various configuration options can be changed for LDoc to modify its produced output; a list can be seen in LDoc’s documentation.