----------------------------
Documentation cheat sheet
----------------------------

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

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: :github-file:`experiments/psychtoolbox/general`

For a file:

- Syntax: ``:github-file:`docs/source/4-meg-experiments-gallery/experiments/psychtoolbox/attention-experiment.rst```
- Rendered: :github-file:`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: :github-file:`Psychtoolbox Scripts <experiments/psychtoolbox/general>`

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 <../6-meg-pipeline-gallery/notebooks/fieldtrip/fieldtrip_kit_restingstate.ipynb>`_

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``).

.. code-block:: rst

   .. 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
^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: rst

   **Docs**

   .. checklist::

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

   **Release**

   .. checklist::

      - [ ] Changelog
      - [ ] Tag and publish