docs: use MarkDown for option docs

docs/add-roundcube.rst

@@ -1,5 +1,5 @@
 Add Roundcube, a webmail
-=======================
+========================
 
 The NixOS module for roundcube nearly works out of the box with SNM. By
 default, it sets up a nginx virtual host to serve the webmail, other web

docs/conf.py

@@ -18,7 +18,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'NixOS Mailserver'
-copyright = '2020, NixOS Mailserver Contributors'
+copyright = '2022, NixOS Mailserver Contributors'
 author = 'NixOS Mailserver Contributors'
 
 
@@ -28,8 +28,16 @@ author = 'NixOS Mailserver Contributors'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    'myst_parser'
 ]
 
+myst_enable_extensions = [
+    'colon_fence',
+    'linkify',
+]
+
+smartquotes = False
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -50,4 +58,4 @@ html_theme = 'sphinx_rtd_theme'
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+html_static_path = []

docs/howto-develop.rst

@@ -30,8 +30,8 @@ run tests manually. For instance:
 Contributing to the documentation
 ---------------------------------
 
-The documentation is written in RST, build with Sphinx and published
-by `Read the Docs <https://readthedocs.org/>`_.
+The documentation is written in RST (except option documentation which is in MarkDown),
+built with Sphinx and published by `Read the Docs <https://readthedocs.org/>`_.
 
 For the syntax, see `RST/Sphinx Cheatsheet
 <https://sphinx-tutorial.readthedocs.io/cheatsheet/>`_.
@@ -47,11 +47,11 @@ documentation:
    $ firefox ./_build/html/index.html
 
 Note if you modify some NixOS mailserver options, you would also need
-to regenerate the ``options.rst`` file:
+to regenerate the ``options.md`` file:
 
 ::
 
-   $ nix-shell --run generate-rst-options
+   $ nix-shell --run generate-options
 
 Nixops
 ------

docs/requirements.txt

@@ -1,2 +1,4 @@
-sphinx==4.0.2
-sphinx_rtd_theme==0.5.2
+sphinx ~= 5.3
+sphinx_rtd_theme ~= 1.1
+myst-parser ~= 0.18
+linkify-it-py ~= 2.0