AppCUI development

GitHub workflows

Workflow	Trigger	What it does
`ci.yml` (build)	push to `main`, pull requests, manual	builds AppCUI, the examples and the documentation samples on Linux, macOS and Windows
`gh-pages.yml`	push to `main`, pull requests that change `docs` or `AppCUI.hpp`, manual	builds this documentation (Doxygen + Sphinx, warnings are errors); on `main` it is published to the `gh-pages` branch
`increase_version.yml`	push to `main`, manual	increments `APPCUI_VERSION` in `AppCUI.hpp` (do not edit it by hand)
`build-and-deploy-release.yml` / `deploy_release.yml`	push to `main` / manual	build the release binaries

Workflows with a manual trigger can be started for any branch from the Actions page (Run workflow); for the others, a draft pull request runs them.

Documentation

The documentation is built with Sphinx. The guides are the .rst files of docs/source; the API reference is generated from AppCUI/include/AppCUI.hpp by Doxygen (which parses the header into XML) and Breathe (which renders the XML in Sphinx). The pages of the API reference (docs/source/api) are generated by docs/source/_ext/appcui_api.py at every build and are not stored in the repository.

Building it locally:

install Doxygen (winget install DoxygenProject.Doxygen, brew install doxygen or a release from https://www.doxygen.nl/download.html) - or point the DOXYGEN environment variable to the executable. The CI uses Doxygen 1.18.0; older versions (for example the one packaged by some Linux distributions) may produce different XML and additional warnings;
install the Python packages (a virtual environment is recommended):
```
cd docs
python -m pip install -r requirements.txt
```

build the HTML pages (the result is in docs/build/html):

make html                                   # Linux / macOS
make.bat html                               # Windows
python -m sphinx -W -b html source build/html   # what the CI runs (warnings are errors)

Without Doxygen, APPCUI_DOCS_SKIP_API=1 builds the guides only (the API reference is replaced by a placeholder).

Documenting the API

every public declaration of AppCUI.hpp appears in the API reference, documented or not;
a /// comment just before a declaration (or ///< after a member on the same line) becomes its description; the first sentence is the summary. Plain // comments are not part of the documentation;
namespace descriptions are in docs/doxygen/namespaces.dox;
code shown in the guides lives in docs/snippets and is included with literalinclude: the samples are compiled with the examples, so a change of the API that breaks them breaks the build.