FIXME: The example below uses a deprecated function.
..todo::
Add a section about configuration file formats.
To show or hide todos in the rendered output, set in your ``conf.py``:
..code-block:: python
todo_include_todos = True # shows todos in the HTML output
# todo_include_todos = False # hides them
When ``True``, all ``.. todo::`` directives appear inline. Use this for local reviews; keep it ``False`` for public releases unless you want todos visible.
Extensions
----------
Our Sphinx configuration uses the following extensions:
..code-block:: python
extensions = [
'sphinx.ext.extlinks',
'sphinx_lesson',
'sphinx.ext.todo',
]
-**``sphinx.ext.todo``**– enables the ``.. todo::`` directive and the ``todo_include_todos`` setting.
-**``sphinx_lesson``**– provides lesson‑specific markup (see its documentation for details).
-**``sphinx.ext.extlinks``**– creates short aliases for long, repetitive URLs.
External links (extlinks)
~~~~~~~~~~~~~~~~~~~~~~~~~
The ``extlinks`` extension defines convenient shortcuts. For each alias you write ``:<alias>:<suffix>``, and Sphinx expands it into a full URL.
-``:source:`v1.1_010/firefox/00-proxy.yml``` → links to the raw file at that tag, displayed as ``source: v1.1_010/firefox/00-proxy.yml``
-``:tiramisu:`configuration.html``` → links to the Tiramisu documentation, displayed as ``tiramisu: configuration.html``
-``:tutorial:`README.md``` → links to the rougail-tutorials file, displayed as ``tutorial README.md``
The first string in each tuple is the URL pattern (the ``%s`` is replaced by your custom text). The second string is the visible link title (where ``%s`` is again replaced by your custom text).
- Place ``.rst`` files in the ``source/`` directory (or as defined in your Sphinx ``conf.py``).
- One page per logical topic – split long documents into sub-pages and link them with ``toctree``.
- Name files with lowercase letters and hyphens instead of underscores or spaces (e.g. ``api-reference.rst``).
Example – a typical page
------------------------
..code-block:: rst
Using the Logger
================
Basic setup
-----------
Add the following to your configuration:
..code-block:: python
import logging
logging.basicConfig(level=logging.INFO)
Advanced filtering
~~~~~~~~~~~~~~~~~~
For more complex filtering, see :ref:`custom-filters`.
FIXME: The example above should mention log levels.
..todo::
Add a section about rotating log files.
For any questions about Sphinx directives or reStructuredText syntax, check the `official Sphinx documentation <https://www.sphinx-doc.org/>`_.
Displaying YAML files
-------------------------
We host our data files on a remote forge. To include and display YAML files directly from that remote repository, we use a custom directive called **``extinclude``**.
This directive works like the standard ``.. include::`` but fetches content from a **remote URL** instead of a local file.
YAML files coming from a data repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the following syntax to include a remote YAML file with syntax highlighting:
This fetches the remote text file and renders it with terminal-style formatting (typically a dark background, monospaced font, and command-line appearance).
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Displaying HTML output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To include and display an HTML file from the remote forge, use the ``raw`` directive with the ``output`` class:
All three directives fetch content from our remote forge at build time, ensuring the documentation always displays the latest version of the referenced files.
