# Modern, interactive and impactful software documentation with Sphinx, MyST and the Diátaxis framework

Ghislain Vaillant

## ► To cite this version:

Ghislain Vaillant. Modern, interactive and impactful software documentation with Sphinx, MyST and the Diátaxis framework. RSECon24 - Eighth annual conference for Research Software Engineering, Society of Research Software Engineering, Sep 2024, Newcastle, United Kingdom. 10.5281/zenodo.14290305. hal-04827038

HAL Id: hal-04827038

https://inria.hal.science/hal-04827038v1

Submitted on 10 Dec 2024

HAL is a multi-disciplinary open access archive for the deposit and dissemination of scientific research documents, whether they are published or not. The documents may come from teaching and research institutions in France or abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est destinée au dépôt et à la diffusion de documents scientifiques de niveau recherche, publiés ou non, émanant des établissements d'enseignement et de recherche français ou étrangers, des laboratoires publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
<figure><img src="image_2.png" /></figure>

# Modern, interactive and impactful software documentation

with Sphinx, MyST and the Diátaxis framework

Ghislain Vaillant
<figure><img src="image_3.png" /></figure>

# Target audience

*How to write **good** software documentation?*
<figure><img src="image_4.png" /></figure>

# Sommaire

1. Impactful documentation with Diátaxis

2. Modern documentation with Sphinx and MyST

3. Tooling and automation
01

# Impactful documentation with Diátaxis

<figure><img src="image_5.png" /></figure>
<figure><img src="image_6.png" /></figure>

Domain of craft

Action

Acquisition

Application

Cognition

<footnote n="1">¹Procida, D. Diataxis documentation framework. https://diataxis.fr/</footnote>
Map of documentation

TUTORIALS

LEARNING

Action

HOW-TO GUIDES

GOALS

Acquisition

Application

UNDERSTANDING

EXPLANATION

Cognition

INFORMATION

REFERENCE

<footnote n="1">¹Procida, D. Diataxis documentation framework. https://diataxis.fr/</footnote>
<figure><img src="image_7.png" /></figure>

<figure><img src="image_8.png" /></figure>

<footnote n="1">¹Procida, D. Diataxis documentation framework. https://diataxis.fr/</footnote>
<figure><img src="image_9.png" /></figure>

Overlapping needs

<table><thead><tr><td>Practitioner's needs</td><td>addressed by</td><td>and by</td></tr></thead><tbody><tr><td>Develop practical knowledge</td><td>Tutorials</td><td>Cookbook</td></tr><tr><td>Serve the application of skills</td><td>Reference</td><td>Cookbook</td></tr><tr><td>Provide theoretical knowledge</td><td>Reference</td><td>Explanation</td></tr><tr><td>Serve the acquisition of skills</td><td>Tutorials</td><td>Explanation</td></tr></tbody></table>
Distinctive concerns

<table><thead><tr><td>Material</td><td>Guidance</td><td>Expectations</td></tr></thead><tbody><tr><td>Tutorials</td><td>Lesson</td><td>Teach, lead, educate</td></tr><tr><td>Cookbook</td><td>Goals</td><td>Guide, follow, achieve</td></tr><tr><td>Reference</td><td>Information</td><td>State, inform, describe</td></tr><tr><td>Explanation</td><td>Topic</td><td>Understand, discuss, clarify</td></tr></tbody></table>
02
Modern documentation with Sphinx and MyST

<figure><img src="image_10.png" /></figure>
<figure><img src="image_11.png" /></figure>

# Getting started

1. Install the base set of dependencies
   `pip install sphinx mystParser`

2. Bootstrap the documentation project
   `sphinx-quickstart docs`

3. Enable support for MyST
   `# docs/conf.py`

`extensions = [

4. Start editing docs/index.md
<figure><img src="image_12.png" /></figure>

# MyST Markdown

MyST Markdown = CommonMark + MyST roles and directives

## Example of a MyST role

For more information, please check this section
[ref]`some-section`.

## Example of a MyST directive

````admonition``` Warning title
:class: warning

Some details about the warning
```
<figure><img src="image_13.png" /></figure>

# MyST extensions

Optional MyST syntax enhancements can be enabled through extensions<fnref n="1" />.

## Enable code fences using colons

```
# docs/conf.py
```

```
myst_enable_extensions = ["colon_fence"]
```

## Admonition rendered as Markdown

```
:::{admonition} Warning title
```

```
:class: warning
```

```
Some **details** about the _warning_
```

```
:::
```

<footnote n="1">¹https://myst-pARSER.readthedocs.io/en/latest/syntax/optional.html</footnote>
<figure><img src="image_14.png" /></figure>

# Sphinx extensions

Sphinx extensions are usable with MyST markdown.

## Enable support for mermaid graphs

```ini
# docs/conf.py
```

```python
extensions = ["sphinxcontrib.mermaid"]
```

## Using the mermaid directive

```ini
```{mermaid}
flowchart LR
    Start --> Stop
```

<figure><img src="image_15.png" /></figure>
<figure><img src="image_16.png" /></figure>

# Autogenerated reference documentation

Use the `sphinx-autoapi`<fnref n="2" /> extension to automatically generate reference documentation from docstrings.

Reference documentation will be composed from module / class / function docstrings and cached for faster builds. Unlike `sphinx-autodoc`, it does not rely on package imports.

## Configured with

```
# docs/conf.py
extensions = ["autoapi.extension"]
autoapi_dirs = ["../src"]
autoapi_root = "reference"
```

<footnote n="2">²https://sphinx-autoapi.readthedocs.io/</footnote>
<figure><img src="image_17.png" /></figure>

# Literate programming with MyST notebooks

Use the `myst-nb`<fnref n="3" /> extension to support writing and versioning Jupyter notebooks in MyST Markdown.

## Configured with

```python
# docs/conf.py
extension = ["myst_nb"]
```

## Executable code block

```python
```{code-block}
print("hello world!")
```

<footnote n="3">³https://myst-nb.readthedocs.io</footnote>
<figure><img src="image_18.png" /></figure>

# Interactive notebooks with sphinx-thebe

Use the `sphinx-thebe`<fnref n="4" /> extension to support interactive execution of notebooks with Binder<fnref n="5" />.

## Configured with

```python
# docs/conf.py
extension = [
    "myst-nb",
    "sphinx-thebe",
]
```

## Launch button

```html
```{thebe-button}
```

## Interactive code block

```python
```{code-block}
:class: thebe

print("hello world!")
```

<footnote n="4">⁴https://sphinx-thebe.readthedocs.io</footnote>

<footnote n="5">⁵https://mybinder.org/</footnote>
## 03
# Tooling and automation

<figure><img src="image_19.png" /></figure>
<figure><img src="image_20.png" /></figure>

# Project setup

* Bootstrap Sphinx project with sphinx-quickstart

* Setup interactive editing with sphinx-autobuild

* Use a separate group for documentation dependencies

```ini
# pyproject.toml
[project.Optional-dependencies]
docs = [
```

```python
"sphinx < 9", # Avoid breakage with sphinx-quickstart
"myst-nb",    # Support for MyST syntax and notebooks
"numpydoc",  # Support for NumPy's docstrings
"sphinx-autoapi", # To generate API documentation
"sphinx-autobuild", # For interactive editing
"sphinx-design", # For additional web-components
# ...
]
```
<figure><img src="image_21.png" /></figure>

# Project maintenance

Consider providing appropriate maintenance commands.

```
# pyproject.toml
[tool.hatch.envs/docs]
features = ["docs"] # Add more groups if needed
python = "3.12" # Freeze Python version for docs
```

```
[tool.hatch.envs/docs.scripts]
build = "sphinx-build docs/ docs/_build/html {args}"
serve = "sphinx-autobuild docs/ docs/_build/html {args}"
clean = "rm -rf docs/_build"
```

```
# console
hatch run docs:build
hatch run docs:serve
hatch run docs:clean
```
<figure><img src="image_22.png" /></figure>

# Automated deployments

Use any of readthedocs, GitLab pages or self-hosting, with a custom domain eventually.

```yaml
# .readthedocs.yaml
version: 2
python:
  install:
    - method: pip
      path: './'
    extra_requirements:
      - docs  # Add more groups if needed
build:
  os: ubuntu-22.04
tools:
  python: '3.12'
```
<figure><img src="image_23.png" /></figure>

## Take away

* Apply Diataxis to raise your documentation's impact

* Understand documentation needs and concerns

* Adapt documentation structure and content accordingly

* Avoid overlapping content, favour cross-referencing instead

* Use Sphinx with MyST for a modern and interactive experience

* Sphinx with modern plugins provides a rich editing experience

* MyST is expressive enough to fullfil most documentation needs

* MyST notebooks are easier to keep track of and review

* Invest time and efforts in automation and maintenance setup

* Treat your documentation as a separate project

* Make your documentation builds reproducible
Merci.

<figure><img src="image_24.png" /></figure>