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.
Where a change goes
Section titled “Where a change goes”- Documentation of released behaviour (a new page about an existing feature, a correction, a reorganisation): start from
mainand open the merge request tomain. The page is online at the end of its pipeline, thenmainis merged back intodev, as for a hotfix. Starting fromdevwould bring unreleased features intomainwith 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.
Preview a change
Section titled “Preview a change”On your machine
Section titled “On your machine”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):
corepack enablepnpm installpnpm devOpen 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.
In the merge request
Section titled “In the merge request”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.
Where pages go
Section titled “Where pages go”The site has one section per audience, and each page is one of the four types of Diátaxis:
| Section | For | Folder |
|---|---|---|
| Use madbot | people who use madbot | use/ |
| Run an instance | people who install and run an instance | run/ |
| Automate with the API | people who call the REST API from their own scripts | api/ |
| Extend madbot | developers who write plugins | extend/ |
| Contribute | people who change madbot | contribute/ |
- 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 plugins_api reference
Section titled “The plugins_api reference”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_apiand, in each one, the names listed in its__all__. A new public class goes into the__all__of its module and ofplugins_api/__init__.py. - Major versions:
documentation/plugins-api.config.mjslists the majors still supported by plugins. The current one is read fromplugin_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.
The files for coding assistants
Section titled “The files for coding assistants”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 REST API reference
Section titled “The REST API reference”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 fromapi/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.
Writing rules
Section titled “Writing rules”- One audience and one type per page. A how-to guide does not explain a concept at length: it links to the explanation.
- 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.
- Interface labels are quoted exactly as
client/locales/en.jsonshows them (fr.jsonfor French pages). - Examples come from several disciplines: a soil core, a material, a cohort participant, an archive document. Biology is one example among others.
- 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.
- English is the source language. French comes first for the home page,
use/andrun/;api/,extend/andcontribute/stay in English. A French page lives underfr/, with the same path as the English one. A page without a French version is shown in English, with a notice.
Syntax
Section titled “Syntax”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,CardandBadge, 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.

