Building code documentation#

What you will need

What you will get

  • Ability to build and preview a Jupyter Book for your project

Duckietown projects ship with a ready‑to‑use Jupyter Book skeleton under /docs/src. Refer to the Book Writer Manual for details on the supported features and a syntax cheat sheet.

Quick build command#

From the project root:

dts docs build

dts launches a container, resolves dependencies, and writes the rendered HTML to /docs/html.

Mixing reStructuredText inside Markdown#

MyST supports the {eval-rst} directive, enabling adding raw rST blocks in a .md file — useful when requiring constructs that Markdown lacks.

```{eval-rst}
.. note::
   A note written in reStructuredText.
.. include:: ./include-rst.rst
```

Rendered result

Note

A note written in reStructuredText.

Automatic API generation (advanced)#

Sphinx can parse docstrings and create an API reference automatically.

To enable this:

  1. Add sphinx.ext.autodoc and, if desired, autodoc_typehints to docs/src/conf.py.

  2. Create stub files (e.g., reference/api.rst) that call .. automodule:: or .. autofunction::.

  3. Re‑run dts docs build.

See the Developers section of the official Jupyter Book guide for detailed instructions.