Skip to content
scope-profiler
Projects

Building the docs

The site in docs/ is built with Astro and Starlight. It has four kinds of pages:

  • Hand-written pages in docs/src/content/docs/, as Markdown or MDX. Do not put .mdx files in guide/: the notebook tool deletes the .mdx pages there that it did not generate.
  • Tutorials and most guides, converted from the Jupyter notebooks in notebooks/ by starlight-notebooks: each notebook is executed and its outputs (text, images, tables) are written into an MDX page. notebooks/tutorials/ holds the tutorials and notebooks/guides/ the guides; both are built into the guide/ section (the tool builds one folder into one section), so a tutorial is at /guide/01-getting-started/. The code in these pages is therefore run on every docs build. The guides for C, Fortran, LIKWID and MCP, which need a compiler, hardware or an MCP client, stay hand-written Markdown in docs/src/content/docs/guide/.
  • API reference, generated from the docstrings by starlight-pydocs, one page per module. The Python API page places single objects among prose with <Autodoc name="..." />.
  • Command output: docs/generate_docs_outputs.py runs the CLI and the API and writes their output to docs/src/generated/, which the MDX pages import (?raw) instead of copying it into a code fence.

The figures in figures/ and the @scope-profiler/plotly sources in packages/plotly/src/ are served as they are, at figures/ and plotly/ of the site (docs/public/ links to them), so the interactive pages always use the checkout’s package. Refresh the figures with make figures; a docs build only uses them.

The configuration (defineDocs in docs/astro.config.mjs), the look, the header, the notebook tool and the build workflow come from the shared starlight-theme of the max-models projects; change them there, and update the version in docs/package.json and .github/workflows/docs.yml to pick up a new release.

Requirements

Section titled “Requirements”
  • Node 22 or newer.
  • The package installed with the docs extra: pip install -e ".[docs]".
  • An MPI implementation (mpiexec) for the MPI examples of the generated output.

Commands

Section titled “Commands”
Terminal window
make docs-install     # npm packages and the Python docs extra
make docs-notebooks   # execute notebooks/**/*.ipynb and convert them to pages
make docs-outputs     # run the CLI and API examples into docs/src/generated/
make docs-dev         # live preview at http://localhost:4321/scope-profiler/
make docs-build       # the static site in docs/dist, as in CI
make docs-preview     # serve docs/dist
make docs-clean       # remove generated pages and build output

make docs-notebooks only reruns a notebook whose cells changed since the last run; pass FORCE=1 to rerun all of them.