summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorCalum Lind <calumlind+deluge@gmail.com>2021-12-12 15:29:41 +0000
committerCalum Lind <calumlind+deluge@gmail.com>2021-12-12 18:16:21 +0000
commit24aa48187e3dd34daf5d4cb8c7d01c839141c9b7 (patch)
tree40a3d5d87f91892b072884b3486242b326899224
parent342cca436766febd122aaf94395355ec4baff894 (diff)
downloaddeluge-24aa48187e3dd34daf5d4cb8c7d01c839141c9b7.tar.gz
deluge-24aa48187e3dd34daf5d4cb8c7d01c839141c9b7.tar.bz2
deluge-24aa48187e3dd34daf5d4cb8c7d01c839141c9b7.zip
[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
-rw-r--r--DEPENDS.md6
-rw-r--r--docs/requirements.txt4
-rw-r--r--docs/source/conf.py19
-rw-r--r--docs/source/contributing/index.md12
-rw-r--r--docs/source/contributing/testing.md6
-rw-r--r--docs/source/devguide/how-to/index.md12
-rw-r--r--docs/source/devguide/index.md13
-rw-r--r--docs/source/devguide/packaging/index.md10
-rw-r--r--docs/source/devguide/packaging/release.md2
-rw-r--r--docs/source/devguide/tutorials/index.md7
-rw-r--r--docs/source/how-to/index.md16
-rw-r--r--docs/source/how-to/launchd-service.md4
-rw-r--r--docs/source/how-to/systemd-service.md8
-rw-r--r--docs/source/intro/index.md7
-rw-r--r--docs/source/releases/index.md9
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 <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>
+```
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 <tutorials/index>
+how-to/index
+Packaging <packaging/index>
+../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 <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)
-- [Create launchd services for macOS](launchd-service.md)
-- [Create NSSM services for Windows](nssm-service.md)
+```{toctree}
+:titlesonly:
+
+Create systemd services for Linux <systemd-service>
+Create launchd services for macOS <launchd-service>
+Create NSSM services for Windows <nssm-service>
+```
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 <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
```
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
+```
<!--
2. Using Deluge
diff --git a/docs/source/releases/index.md b/docs/source/releases/index.md
index d72588465..69778a036 100644
--- a/docs/source/releases/index.md
+++ b/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]
-- [Deluge 2.0 release notes](2.0.md)
+```{toctree}
+:titlesonly:
+
+../changelog
+2.0
+```
[git commit log]: http://git.deluge-torrent.org/deluge/log/?h=master
-[changelog]: ../changelog.md