Skip to main content

Publishing Documentation

Your project's documentation can live in the workspace next to its simulations, so the description of a plant model or a controller sits beside the runs that test it. CMODEL_DOCUMENT() makes a small program that checks a documentation folder and uploads it to a documentation project in your workspace.

Documentation projects are part of the paid plans, which have private workspaces. The free workspace, which all free accounts share, has none (see Pricing Models).

tip

If you use Claude Code, the cppmodel:documentation skill of the CppModel Claude Code plugin writes and maintains a concise document for a plant model and the controller it exercises.

The program​

#include <cppmodel/CModel.h>

CMODEL_DOCUMENT()
find_package(cppmodel REQUIRED)

add_executable(publish_docs publish_docs.c)
target_link_libraries(publish_docs PRIVATE cppmodel::cppmodel)
cppmodel_deploy_runtime(publish_docs)
./build/publish_docs --project heater --docs docs --check   # check only: nothing uploaded, no sign-in needed
./build/publish_docs --project heater --docs docs           # check, then upload
OptionMeaning
--project <name>Required. 1 to 64 letters, digits, ., _ or -, starting with a letter or digit.
--docs <folder>Required. The documentation folder.
--checkChecks the folder only.

The upload creates the project, or replaces its whole documentation set. It signs in the same way as a simulation run (see Running the simulation). The program exits with 0 when the check, and the upload, passed, and 1 otherwise.

From C you can also call CppModel_uploadDocs(project, folder, checkOnly), and from C++ cppmodel::UploadDocs(project, folder, checkOnly) or cppmodel::UploadDocsFromCommandLine().

The folder​

The folder is either:

  • An MkDocs project: a folder with mkdocs.yml, whose docs_dir (docs by default) holds the pages. The site name and navigation come from its site_name and nav, and only mkdocs.yml and the docs_dir are uploaded.
  • Just the docs: Markdown pages and the images they use. The navigation follows the folder tree, index.md first, and each page's title is its first # heading.

What is checked​

Nothing is uploaded unless every check passes. A failed check lists each problem with its file and line.

  • Links: every relative link and image resolves to a file in the folder. Only the documentation is uploaded, so a link to source code such as ../src/Heater.c would break. Link to a page instead, or use an absolute https:// link.
  • File types: every file is one the workspace keeps: .md, .markdown, .png, .jpg, .jpeg, .gif, .svg, .webp, .pdf, .txt, .csv or .json. Hidden files are ignored.
  • Navigation: every page in the MkDocs nav exists.
  • Size: at most 5000 files and 300 MB, and a zip of at most 100 MB.

Writing for the workspace​

The workspace shows the pages like an MkDocs site, with navigation, tables, highlighted code, TeX math ($...$ and $$...$$) and admonitions (!!! note). Mermaid and PlantUML diagrams aren't drawn, so use images for diagrams instead. A link to a simulation's page in the workspace opens it next to the documentation.

In CI​

Check the documentation on every change, and upload it from your main branch:

./build/publish_docs --project heater --docs docs --check   # pull requests
./build/publish_docs --project heater --docs docs           # main branch, with CPPMODEL_USERNAME and CPPMODEL_PASSWORD

Set CPPMODEL_LOGIN_TIMEOUT=0 in CI, so a missing login fails at once instead of waiting for a browser sign-in.