Documentation cheat sheet

Use this cheat sheet to write correct Sphinx syntax and to reuse the custom helpers available in this documentation.

Sphinx heading conventions 

Please follow the heading adornment conventions used across this repository. Each document has exactly one title, then sections nest in this order:

Level	Overline & Underline	Underline only	Character
Document title	yes	N/A	`-`
Section	N/A	yes	`=`
Sub-section	N/A	yes	`^`
Sub-sub-section	N/A	yes	`"`

Adding an in-page contents tree 

To add a table of contents built from the headings of your page, put the following at the top of the page, just under the title:

.. contents::
   :local:
   :depth: 2

The top of this page uses exactly that directive.

Reference links within the repository 

Referencing code files and directories on GitHub 

For a directory:

Syntax: :github-file:`experiments/psychtoolbox/general`
Rendered: experiments/psychtoolbox/general

For a file:

Syntax: :github-file:`docs/source/4-meg-experiments-gallery/experiments/psychtoolbox/attention-experiment.rst`
Rendered: docs/source/4-meg-experiments-gallery/experiments/psychtoolbox/attention-experiment.rst

Masking the link with custom text (file or directory):

Syntax: :github-file:`Psychtoolbox Scripts <experiments/psychtoolbox/general>`
Rendered: Psychtoolbox Scripts

Referencing Jupyter notebooks rendered by Sphinx 

To reference the notebook source (the .ipynb file on the repository), use the :github-file: role above. To reference the published page of the notebook instead, link to the rendered document:

Syntax: \`Resting state notebook <../6-meg-pipeline-gallery/notebooks/fieldtrip/fieldtrip_kit_restingstate.ipynb>\`_
Rendered: Resting state notebook

Making a checklist 

You can add simple task checklists to any page using the checklist directive.

Note

Checklists are clickable in HTML builds. In PDF or LaTeX they render as static boxes. If the project includes the optional checklist.js, the checkbox state is remembered per browser.

Prerequisites 

The custom extension must be enabled in conf.py:

extensions = [
    # ... other extensions ...
    "_checklist",
]

Basic usage 

Write one task per line inside the directive. Use [ ] for unchecked and [x] for checked (lowercase x).

.. checklist::

   - [ ] Write the introduction
   - [x] Add figures
   - [ ] Final proofreading

Result 

checkbox empty: Write the introduction
checkbox ticked: Add figures
checkbox empty: Final proofreading

Tips 

Start each task with - [ ] or - [x] exactly.
Each task is plain text (no nested markup).
For sub-tasks, add another checklist block under a bullet or subsection.

Example with sections 

**Docs**

.. checklist::

   - [ ] API reference pass
   - [x] Tutorial outline

**Release**

.. checklist::

   - [ ] Changelog
   - [ ] Tag and publish