16. Convert to mkdocs#

Date: 2024-02-15

Status#

Rejected

Context#

Markdown is nicer to write, we have to write using mkdocs for the developer portal and backstage likes it, should we switch to using it?

It can mostly replace sphinx, but there are a few places it falls down:

  • The API docs (mkdocstrings) have some paid for features that we already use in sphinx

  • The plugin landscape is vast, but not well maintained

  • The scientific python community (i.e. numpy, scipy, matplotlib, bluesky) uses sphinx exclusively

  • There are custom directives like the ipython one that we would struggle to replace

Decision#

We will stick with sphinx for now, but use MyST so we can write markdown with it.

Consequences#

We will keep an eye on mkdocs.