From 24aa48187e3dd34daf5d4cb8c7d01c839141c9b7 Mon Sep 17 00:00:00 2001 From: Calum Lind Date: Sun, 12 Dec 2021 15:29:41 +0000 Subject: [PATCH] [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 | 6 +++--- docs/requirements.txt | 4 ++-- docs/source/conf.py | 19 +------------------ docs/source/contributing/index.md | 12 ++++++++---- docs/source/contributing/testing.md | 6 +++--- docs/source/devguide/how-to/index.md | 12 ++++++++++-- docs/source/devguide/index.md | 13 +++++++++---- docs/source/devguide/packaging/index.md | 10 +++++++--- docs/source/devguide/packaging/release.md | 2 +- docs/source/devguide/tutorials/index.md | 7 ++++++- docs/source/how-to/index.md | 16 ++++++++++++---- docs/source/how-to/launchd-service.md | 4 ++-- docs/source/how-to/systemd-service.md | 8 ++++---- docs/source/intro/index.md | 7 ++++++- docs/source/releases/index.md | 9 ++++++--- 15 files changed, 80 insertions(+), 55 deletions(-) diff --git a/DEPENDS.md b/DEPENDS.md index 8f39eeb2d..d15824446 100644 --- a/DEPENDS.md +++ b/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] diff --git a/docs/requirements.txt b/docs/requirements.txt index c8a0d0546..ff363e0ff 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -sphinx==2.0.* -recommonmark==0.4.* +sphinx==4.* +myst-parser sphinx_rtd_theme sphinxcontrib-spelling diff --git a/docs/source/conf.py b/docs/source/conf.py index 267e562af..f7db27efd 100644 --- a/docs/source/conf.py +++ b/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) diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md index afdead24d..8c07a76b1 100644 --- a/docs/source/contributing/index.md +++ b/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) -- [Running tests](testing.md) -- [Documentation contributions](documentation.md) -- [Translation contributions](translations.md) +```{toctree} +:titlesonly: + +code +testing +documentation +translations +``` diff --git a/docs/source/contributing/testing.md b/docs/source/contributing/testing.md index 8d9d1f31d..4df8ca669 100644 --- a/docs/source/contributing/testing.md +++ b/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 diff --git a/docs/source/devguide/how-to/index.md b/docs/source/devguide/how-to/index.md index 93a43fce1..e63c7713b 100644 --- a/docs/source/devguide/how-to/index.md +++ b/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 +``` ## 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 +``` diff --git a/docs/source/devguide/index.md b/docs/source/devguide/index.md index bde04b3e0..436a72a11 100644 --- a/docs/source/devguide/index.md +++ b/docs/source/devguide/index.md @@ -2,7 +2,12 @@ This is a guide to help with developing Deluge. -- [Tutorials](tutorials/index.md) -- [How-to guides](how-to/index.md) -- [Packaging](packaging/index.md) -- [Changelog](../changelog.md) +```{toctree} +:titlesonly: + +Tutorials +how-to/index +Packaging +../changelog +../depends +``` diff --git a/docs/source/devguide/packaging/index.md b/docs/source/devguide/packaging/index.md index 9da6a27d7..aa7293ab4 100644 --- a/docs/source/devguide/packaging/index.md +++ b/docs/source/devguide/packaging/index.md @@ -1,5 +1,9 @@ # Packaging documentation -- [Release checklist](release.md) -- [Launchpad recipe](launchpad-recipe.md) -- [Windows Packaging](windows.md) +```{toctree} +:titlesonly: + +release +launchpad-recipe +windows +``` diff --git a/docs/source/devguide/packaging/release.md b/docs/source/devguide/packaging/release.md index 892b5fcde..afd7e07a7 100644 --- a/docs/source/devguide/packaging/release.md +++ b/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 diff --git a/docs/source/devguide/tutorials/index.md b/docs/source/devguide/tutorials/index.md index 36a8abf84..2a4725231 100644 --- a/docs/source/devguide/tutorials/index.md +++ b/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> +``` diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md index 9ef1ddde6..7005a3414 100644 --- a/docs/source/how-to/index.md +++ b/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 +``` ## 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) -- [Create launchd services for macOS](launchd-service.md) -- [Create NSSM services for Windows](nssm-service.md) +```{toctree} +:titlesonly: + +Create systemd services for Linux +Create launchd services for macOS +Create NSSM services for Windows +``` diff --git a/docs/source/how-to/launchd-service.md b/docs/source/how-to/launchd-service.md index b988a19e3..53c21bef5 100644 --- a/docs/source/how-to/launchd-service.md +++ b/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 ``` diff --git a/docs/source/how-to/systemd-service.md b/docs/source/how-to/systemd-service.md index 8c7ac01e8..611ecc13d 100644 --- a/docs/source/how-to/systemd-service.md +++ b/docs/source/how-to/systemd-service.md @@ -30,7 +30,7 @@ sudo adduser 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 ``` diff --git a/docs/source/intro/index.md b/docs/source/intro/index.md index 8342cec1e..ff0f8412e 100644 --- a/docs/source/intro/index.md +++ b/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 +```