Skip to content

Write documentation

This site lives in the documentation/ folder of the madbot repository. It is built with Starlight and published on GitLab Pages from main: it always describes the released madbot.

  • Documentation of released behaviour (a new page about an existing feature, a correction, a reorganisation): start from main and open the merge request to main. The page is online at the end of its pipeline, then main is merged back into dev, as for a hotfix. Starting from dev would bring unreleased features into main with your page.
  • Documentation of an unreleased feature: write it in the feature’s merge request, to dev. It is published with the release.

A merge request that changes something visible to users, people who run an instance, plugin developers or API users updates the documentation in the same merge request: the reviewer reads the code and its documentation together.

From documentation/, with Node.js 22, Corepack and uv (the plugins_api reference runs Griffe through uvx, and the REST API reference reads the schema of api/ through uv):

Terminal window
corepack enable
pnpm install
pnpm dev

Open http://localhost:4321/madbot/madbot/. The page reloads when you save a file. pnpm build builds the whole site and fails on a broken internal link, as the CI does.

The pipeline of a merge request that touches documentation/ builds the site. Open it from the Documentation preview link of the merge request, or from the address printed at the end of the Documentation build job. The preview is kept two weeks.

The Documentation external links job checks the links to other sites. It may fail when a site is down: read its log, but it does not block the merge request. It skips the links to the madbot group on gitlab.com (this repository, the plugins, the issues): gitlab.com rate-limits an anonymous check of the hundreds of source links that the site generates.

The site has one section per audience, and each page is one of the four types of Diátaxis:

SectionForFolder
Use madbotpeople who use madbotuse/
Run an instancepeople who install and run an instancerun/
Automate with the APIpeople who call the REST API from their own scriptsapi/
Extend madbotdevelopers who write pluginsextend/
Contributepeople who change madbotcontribute/
  • Tutorial: a lesson that leads a beginner to a first result.
  • How-to guide: the steps to reach a precise goal, for someone who knows what they want.
  • Reference: a description to look up: commands, settings, roles.
  • Explanation: how something works and why.

Pages live in documentation/src/content/docs/, under the folder of their section. Add a new page to the sidebar of documentation/astro.config.mjs.

The pages under extend/plugins/reference/ are generated from the docstrings of plugin_api/ by starlight-pydocs, at each build: to change them, change the docstrings. They follow the numpy convention, which pixi run lint checks in plugin_api/.

  • What is documented: the modules of plugins_api and, in each one, the names listed in its __all__. A new public class goes into the __all__ of its module and of plugins_api/__init__.py.
  • Major versions: documentation/plugins-api.config.mjs lists the majors still supported by plugins. The current one is read from plugin_api/; an older one from the git tag of its last release. Its pages carry a banner that links to the current major, and the search leaves them out.
  • Links: link to the reference without a version, as /extend/plugins/reference/data_plugins/. That address leads to the current major, so the link stays valid when a new major is released.

Each build also publishes the documentation in the llms.txt format, for coding assistants: /llms.txt lists what is available, /llms-full.txt holds the English pages followed by the plugins_api reference of the current major, and /llms-small.txt an abridged version of the pages. They are generated from the pages by starlight-llms-txt and documentation/src/plugins/llms-txt.mjs: there is nothing to edit by hand.

The pages under api/reference/ are generated by starlight-openapi from the OpenAPI schema of api/, which drf-spectacular writes at each build: to change them, change the views and serializers of the API, or their extend_schema decorators. A merge request that changes the API shows the changed reference in its preview.

  • Version: the overview page shows the version of madbot-api, read from api/pyproject.toml.
  • The build fails when the schema cannot be written, for example when the API does not start: it does not publish a reference without its endpoints.
  • Links: link to an endpoint by its operation id, as /api/reference/operations/workspaces_list/. The build checks that the page exists.
  1. One audience and one type per page. A how-to guide does not explain a concept at length: it links to the explanation.
  2. Version mentions.
    • Users: none. An instance runs the latest release.
    • People who run an instance: name the package version (madbot-api 2.1, an image tag), with a badge such as “Since 2.1”.
    • API users: name the version of madbot-api, with the same badge.
    • Plugin developers: name the version of plugins_api.
    • When to remove them: once the version they compare with is no longer supported. The upgrade guides keep the history.
  3. Interface labels are quoted exactly as client/locales/en.json shows them (fr.json for French pages).
  4. Examples come from several disciplines: a soil core, a material, a cohort participant, an archive document. Biology is one example among others.
  5. Screenshots are taken from a local instance with a fictitious account. When a screenshot is missing, say so in the text rather than using an old one.
  6. English is the source language. French comes first for the home page, use/ and run/; api/, extend/ and contribute/ stay in English. A French page lives under fr/, with the same path as the English one. A page without a French version is shown in English, with a notice.

Pages are Markdown (.md), or MDX (.mdx) when they use components. Starlight adds:

  • asides: :::note, :::tip, :::caution, :::danger, closed with :::;
  • components such as Tabs, Steps, Card and Badge, in MDX pages.

Write internal links from the root of the site, with a trailing slash: [the roles](/use/reference/roles/). The build adds the path under which the site is served.