[Docs] Replace recommonmark with MyST parser

We used recommonmark so that we can use markdown in sphinx but it is
buggy and now so switch to better supported MyST-parser.

* Fixed incorrect heading warnings in markdown.
* Added sphinx toctree to markdown using directive as required by MyST.
* Upgraded Sphinx to 4.3

Ref: https://myst-parser.readthedocs.io

DEPENDS.md

@@ -30,11 +30,11 @@ All modules will require the [common](#common) section dependencies.
 - [Pillow] - Optional: Support for resizing tracker icons.
 - [dbus-python] - Optional: Show item location in filemanager.
 
-#### Linux and BSD
+### Linux and BSD
 
 - [distro] - Optional: OS platform information.
 
-#### Windows OS
+### Windows OS
 
 - [pywin32]
 - [certifi]
@@ -52,7 +52,7 @@ All modules will require the [common](#common) section dependencies.
 - [librsvg] _>= 2_
 - [libappindicator3] w/GIR - Optional: Ubuntu system tray icon.
 
-#### MacOS
+### MacOS
 
 - [GtkOSXApplication]
 

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx==2.0.*
+sphinx==4.*
-recommonmark==0.4.*
+myst-parser
 sphinx_rtd_theme
 sphinxcontrib-spelling

docs/source/conf.py

@@ -14,8 +14,6 @@ import os
 import sys
 from datetime import date
 
-from recommonmark.states import DummyStateMachine
-from recommonmark.transform import AutoStructify
 from six.moves import builtins
 from sphinx.ext import apidoc
 from sphinx.ext.autodoc import ClassDocumenter, bool_option
@@ -50,6 +48,7 @@ extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.coverage',
     'sphinxcontrib.spelling',
+    'myst_parser',
 ]
 
 napoleon_include_init_with_doc = True
@@ -59,7 +58,6 @@ napoleon_use_rtype = False
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
 source_suffix = ['.rst', '.md']
 
 # The master toctree document.
@@ -295,19 +293,6 @@ def maybe_skip_member(app, what, name, obj, skip, options):
         return True
 
 
-# Monkey patch to fix recommonmark 0.4 doc reference issues.
-orig_run_role = DummyStateMachine.run_role
-
-
-def run_role(self, name, options=None, content=None):
-    if name == 'doc':
-        name = 'any'
-    return orig_run_role(self, name, options, content)
-
-
-DummyStateMachine.run_role = run_role
-
-
 # Run the sphinx-apidoc to create package/modules rst files for autodoc.
 def run_apidoc(__):
     cur_dir = os.path.abspath(os.path.dirname(__file__))
@@ -329,5 +314,3 @@ def run_apidoc(__):
 def setup(app):
     app.connect('builder-inited', run_apidoc)
     app.connect('autodoc-skip-member', maybe_skip_member)
-    app.add_config_value('recommonmark_config', {}, True)
-    app.add_transform(AutoStructify)

docs/source/contributing/index.md

@@ -3,7 +3,11 @@
 Deluge is an open-source project, and relies on its community of users to keep
 getting better.
 
-- [Code contributions](code.md)
+```{toctree}
-- [Running tests](testing.md)
+:titlesonly:
-- [Documentation contributions](documentation.md)
+
-- [Translation contributions](translations.md)
+code
+testing
+documentation
+translations
+```

docs/source/contributing/testing.md

@@ -38,7 +38,7 @@ Running the tests for a specific plugin (requires [pytest](https://pypi.python.o
 
 All the tests for Deluge can be run using [Tox](https://pypi.python.org/pypi/tox)
 
-#### See available targets:
+### See available targets:
 
     tox -l
     py27
@@ -46,11 +46,11 @@ All the tests for Deluge can be run using [Tox](https://pypi.python.org/pypi/tox
     lint
     docs
 
-#### Run specific test:
+### Run specific test:
 
     tox -e py3
 
-#### Verify code with pre-commit:
+### Verify code with pre-commit:
 
     tox -e lint
 

docs/source/devguide/how-to/index.md

@@ -4,7 +4,11 @@ A collection of guides for specific issues or to cover more detail than the tuto
 
 ## Web JSON-RPC
 
-- [Connect to JSON-RPC using curl](curl-jsonrpc.md)
+```{toctree}
+:titlesonly:
+
+Connect to JSON-RPC using curl <curl-jsonrpc>
+```
 
 ## Plugins
 
@@ -12,4 +16,8 @@ A collection of guides for specific issues or to cover more detail than the tuto
 - [Create a plugin](create-plugin.md)
 -->
 
-- [Update 1.3 plugin for 2.0](update-1.3-plugin.md)
+```{toctree}
+:titlesonly:
+
+Update 1.3 plugin for 2.0 <update-1.3-plugin>
+```

docs/source/devguide/index.md

@@ -2,7 +2,12 @@
 
 This is a guide to help with developing Deluge.
 
-- [Tutorials](tutorials/index.md)
+```{toctree}
-- [How-to guides](how-to/index.md)
+:titlesonly:
-- [Packaging](packaging/index.md)
+
-- [Changelog](../changelog.md)
+Tutorials <tutorials/index>
+how-to/index
+Packaging <packaging/index>
+../changelog
+../depends
+```

docs/source/devguide/packaging/index.md

@@ -1,5 +1,9 @@
 # Packaging documentation
 
-- [Release checklist](release.md)
+```{toctree}
-- [Launchpad recipe](launchpad-recipe.md)
+:titlesonly:
-- [Windows Packaging](windows.md)
+
+release
+launchpad-recipe
+windows
+```

docs/source/devguide/packaging/release.md

@@ -46,4 +46,4 @@
 [wikipedia]: http://en.wikipedia.org/wiki/Deluge_%28software%29
 [launchpad]: https://translations.launchpad.net/deluge
 [translation]: ../../contributing/translations.md
-[release notes]: ../../release/index.md
+[release notes]: ../../releases/index.md

docs/source/devguide/tutorials/index.md

@@ -2,4 +2,9 @@
 
 A list of articles to help developers get started with Deluge.
 
-- [Development setup](01-setup.md)
+```{toctree}
+:numbered: 1
+:titlesonly:
+
+Development setup <01-setup>
+```

docs/source/how-to/index.md

@@ -4,7 +4,11 @@ A collection of guides covering common issues that might be encountered using De
 
 ## GTK UI
 
-- [Set default torrent application](set-mime-type.md)
+```{toctree}
+:titlesonly:
+
+Set default torrent application <set-mime-type>
+```
 
 ## Deluge as a service
 
@@ -14,6 +18,10 @@ shutdown and automatically restart them if they crash.
 
 The Deluge daemon deluged and Web UI deluge-web can both be run as services.
 
-- [Create systemd services for Linux](systemd-service.md)
+```{toctree}
-- [Create launchd services for macOS](launchd-service.md)
+:titlesonly:
-- [Create NSSM services for Windows](nssm-service.md)
+
+Create systemd services for Linux <systemd-service>
+Create launchd services for macOS <launchd-service>
+Create NSSM services for Windows <nssm-service>
+```

docs/source/how-to/launchd-service.md

@@ -12,7 +12,7 @@ and will need modified if using other installation methods e.g. `Deluge.app`.
 Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluged.plist`
 containing the following:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluged.plist
     :language: xml
 ```
@@ -29,7 +29,7 @@ sudo launchctl start org.deluge-torrent.deluged
 Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist`
 containing the following:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluge-web.plist
     :language: xml
 ```

docs/source/how-to/systemd-service.md

@@ -30,7 +30,7 @@ sudo adduser <username> deluge
 
 Create the file `/etc/systemd/system/deluged.service` containing the following:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/systemd/deluged.service
     :language: ini
 ```
@@ -47,7 +47,7 @@ sudo mkdir /etc/systemd/system/deluged.service.d/
 Then create a user file `/etc/systemd/system/deluged.service.d/user.conf` with
 the following contents:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/systemd/user.conf
     :language: ini
 ```
@@ -82,7 +82,7 @@ after changes.
 
 Create the file `/etc/systemd/system/deluge-web.service` containing the following:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/systemd/deluge-web.service
     :language: ini
 ```
@@ -99,7 +99,7 @@ sudo mkdir /etc/systemd/system/deluge-web.service.d/
 Then create a user file `/etc/systemd/system/deluge-web.service.d/user.conf` with
 the following contents:
 
-```eval_rst
+```{eval-rst}
 .. literalinclude:: ../../../packaging/systemd/user.conf
     :language: ini
 ```

docs/source/intro/index.md

@@ -3,7 +3,12 @@
 This is a starting point if you are new to Deluge where we will walk
 you through getting up and running with our BitTorrent client.
 
-- [1. Installing Deluge](01-install.md)
+```{toctree}
+:numbered: 1
+:titlesonly:
+
+01-install
+```
 
 <!--
 2. Using Deluge

docs/source/releases/index.md

@@ -3,8 +3,11 @@
 A summary of the important changes in major releases of Deluge. For more details see
 the [changelog] or the [git commit log].
 
-- [Changelog]
+```{toctree}
-- [Deluge 2.0 release notes](2.0.md)
+:titlesonly:
+
+../changelog
+2.0
+```
 
 [git commit log]: http://git.deluge-torrent.org/deluge/log/?h=master
-[changelog]: ../changelog.md