Welcome to the meta section of our documentation where we document how to do documentation!

Edit or add. That’s the primary instruction. You can edit directly on (for example, the edit link on this page takes you to If you aren’t a member of Agaric, GitLab will helpfully offer to fork the documentation to your own namespace so that you can make a merge request with your documentation suggestion.


This documentation page is a good one to copy or refer to for an example of MyST formatting. And of course anyone can come and clean up formatting later.

Where to post what

We like Gitlab’s approach: If you’re not sure where to put something in documentation, or if it even is documentation, write a blog post. Or even, in the Agaric context, just throw it in a raw note (this private repository automatically publishes non-draft notes publicly to

Somewhere is better than nowhere.

Don’t worry about translation.


  • Document closest to where people work:

    • In files or otherwise in the code repository for developers.

    • In the site itself for site managers and content editors, or alternatively in an organization’s already established locations.

  • Topics which are of general application can be abstracted, put in this repository, and linked to at this documentation.


In doing documentation we are living our values of encouraging continuous learning, appreciating new ideas, giving back to the communities we are part of, and valuing long-term relationships.

This documentation

Local preview


sudo apt install python3-sphinx
pip3 install -r requirements.txt


Running this documentation locally:

sphinx-build -b html . _build/html

Useful examples

Including the table of contents of another page

caption: See also


Produces this:

caption: See also