Merging upstream version 2.1.2~dev0+20230529.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

36 files changed, 1937 insertions, 0 deletions

diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..de42439
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,5 @@
+sphinx==4.*
+myst-parser
+sphinx_rtd_theme==1.0.*
+sphinxcontrib-spelling==7.3.0
+sphinx-autodoc-typehints
diff --git a/docs/source/changelog.md b/docs/source/changelog.md
new file mode 120000
index 0000000..699cc9e
--- /dev/null
+++ b/docs/source/changelog.md
@@ -0,0 +1 @@
+../../CHANGELOG.md
\ No newline at end of file
diff --git a/docs/source/conf.py b/docs/source/conf.py
new file mode 100644
index 0000000..0e4a419
--- /dev/null
+++ b/docs/source/conf.py
@@ -0,0 +1,284 @@
+#
+# Deluge documentation build configuration file
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# The contents of this file are pickled, so don't put values in the namespace
+# that aren't pickleable (module imports are okay, they're removed automatically).
+#
+# All configuration values have a default value; values that are commented out
+# serve to show the default value.
+
+import builtins
+import os
+import sys
+from datetime import date
+
+from sphinx.ext import apidoc
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
+
+# If your extensions are in another directory, add it here. If the directory is relative
+# to the documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(
+    os.path.abspath(
+        os.path.join(
+            os.path.join(os.path.dirname(__file__), os.path.pardir), os.path.pardir
+        )
+    )
+)
+# Importing version only possible after add project root to sys.path.
+try:
+    from version import get_version
+except ImportError:
+    from deluge.common import get_version
+
+
+# General configuration
+# ---------------------
+
+needs_sphinx = '2.0'
+suppress_warnings = ['app.add_source_parser']
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.doctest',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.coverage',
+    'sphinxcontrib.spelling',
+    'myst_parser',
+    'sphinx_autodoc_typehints',
+]
+
+napoleon_include_init_with_doc = True
+napoleon_use_rtype = False
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = ['.rst', '.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General substitutions.
+project = 'Deluge'
+current_year = date.today().year
+copyright = '2008-%s, Deluge Team' % current_year  # noqa: A001
+
+# The full version, including alpha/beta/rc tags.
+release = get_version()
+# The short X.Y version.
+version = '.'.join(release.split('.', 2)[:2])
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+# today = ''
+# Else, today_fmt is used as the format for a strftime call.
+today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+# unused_docs = []
+
+# List of directories, relative to source directories, that shouldn't be searched
+# for source files.
+exclude_patterns = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+# default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+# add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+# add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+# show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# Options for spelling
+# --------------------
+spelling_show_suggestions = True
+spelling_word_list_filename = '../spelling_wordlist.txt'
+# Skip Deluge module rst files
+if 'spelling' in sys.argv or 'spellcheck_docs' in sys.argv:
+    exclude_patterns += ['modules']
+
+# Options for HTML output
+# -----------------------
+html_theme = 'sphinx_rtd_theme'
+# The style sheet to use for HTML and HTML Help pages. A file of that name
+# must exist either in Sphinx' static/ path, or in one of the custom paths
+# given in html_static_path.
+# html_style = 'default.css'
+
+# Add font-mfizz for icons.
+html_css_files = [
+    'https://cdnjs.cloudflare.com/ajax/libs/font-mfizz/2.4.1/font-mfizz.min.css'
+]
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+# html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+# html_short_title = None
+
+# The name of an image file (within the static path) to place at the top of
+# the sidebar.
+# html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+html_favicon = '../../deluge/ui/data/pixmaps/deluge.ico'
+
+# 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']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+# html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+# html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+# html_additional_pages = {}
+
+# If false, no module index is generated.
+# html_use_modindex = True
+
+# If false, no index is generated.
+# html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+# html_split_index = False
+
+# If true, the reST sources are included in the HTML build as _sources/<name>.
+# html_copy_source = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+# html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+# html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'delugedoc'
+
+
+# Options for LaTeX output
+# ------------------------
+
+# The paper size ('letter' or 'a4').
+# latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+# latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, document class [howto/manual]).
+latex_documents = [
+    ('index', 'deluge.tex', 'deluge Documentation', 'Deluge Team', 'manual')
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+# latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+# latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+# latex_appendices = []
+
+# If false, no module index is generated.
+# latex_use_modindex = True
+
+
+# Autodoc section
+# ---------------
+
+# Must add these for autodoc to import packages successfully
+builtins.__dict__['_'] = lambda x: x
+builtins.__dict__['_n'] = lambda s, p, n: s if n == 1 else p
+
+autodoc_mock_imports = [
+    'deluge._libtorrent',
+    'twisted',
+    'rencode',
+    'OpenSSL',
+    'PIL',
+    'libtorrent',
+    'psyco',
+    'gi',
+    'cairo',
+    'curses',
+    'win32api',
+    'win32file',
+    'win32process',
+    'win32pipe',
+    'pywintypes',
+    'win32con',
+    'win32event',
+    'pytest',
+    'mock',
+    'mako',
+    'xdg',
+    'zope',
+    'zope.interface',
+]
+
+# Register an autodoc class directive to only include exported methods.
+ClassDocumenter.option_spec['exported'] = bool_option
+
+
+def maybe_skip_member(app, what, name, obj, skip, options):
+    if options.exported and not (
+        hasattr(obj, '_rpcserver_export') or hasattr(obj, '_json_export')
+    ):
+        return True
+
+
+# Run the sphinx-apidoc to create package/modules rst files for autodoc.
+def run_apidoc(__):
+    cur_dir = os.path.abspath(os.path.dirname(__file__))
+    module_dir = os.path.join(cur_dir, '..', '..', 'deluge')
+    ignore_paths = [
+        os.path.join(module_dir, 'plugins'),
+        os.path.join(module_dir, 'tests'),
+    ]
+    argv = [
+        '--force',
+        '--no-toc',
+        '--output-dir',
+        os.path.join(cur_dir, 'modules'),
+        module_dir,
+    ] + ignore_paths
+    apidoc.main(argv)
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)
+    app.connect('autodoc-skip-member', maybe_skip_member)
diff --git a/docs/source/contributing/code.md b/docs/source/contributing/code.md
new file mode 100644
index 0000000..20ccb82
--- /dev/null
+++ b/docs/source/contributing/code.md
@@ -0,0 +1,124 @@
+# Contributing code
+
+## Basic requirements and standards
+
+- A [new ticket](http://dev.deluge-torrent.org/newticket) is required for bugs
+  or features. Search the ticket system first, to avoid filing a duplicate.
+- Ensure code follows the [syntax and conventions](#syntax-and-conventions).
+- Code must pass tests. See [testing](testing.md) document for
+  information on how to run and write unit tests.
+- Commit messages are informative.
+
+## Pull request process:
+
+- Fork us on [GitHub](https://github.com/deluge-torrent/deluge).
+- Clone your repository.
+- Create a feature branch for your issue.
+- Apply your changes:
+  - Add them, and then commit them to your branch.
+  - Run the tests until they pass.
+  - When you feel you are finished, rebase your commits to ensure a simple
+    and informative commit log.
+- Create a pull request on GitHub from your forked repository.
+  - Verify that the tests run by [Travis-ci](https://travis-ci.org/deluge-torrent/deluge)
+    are passing.
+
+## Syntax and conventions
+
+### Code formatting
+
+We use two applications to automatically format the code to save development
+time. They are both run with [pre-commit].
+
+#### Black
+
+- Python
+
+#### Prettier
+
+- JavaScript
+- CSS
+- YAML
+- Markdown
+
+### Common
+
+- Line length: `79` chars.
+- Indent: `4 spaces`, no tabs.
+- All code should use `'single quotes'`.
+
+### Python
+
+We follow [PEP8](http://www.python.org/dev/peps/pep-0008/) and
+[Python Code Style](http://docs.python-guide.org/en/latest/writing/style/)
+which is adhered to with [Black].
+
+- Code '''must''' pass [Black], [flake8] and [isort] source code checkers.
+  (Optionally [Pylint])
+
+        flake8 deluge
+        isort -rc -df deluge
+        pylint deluge
+        pylint deluge/plugins/\*/deluge/
+
+- Using the [pre-commit] application can aid in identifying issues while
+  creating git commits.
+
+#### Strings and bytes
+
+To prevent bugs or errors in the code byte strings (`str`) must be decoded to
+strings (Unicode text strings, `unicode`) on input and then encoded on output.
+
+_Notes:_
+
+- PyGTK/GTK+ will accept `str` (UTF-8 encoded) or `unicode` but will only return
+  `str`. See [GTK3 Unicode] docs.
+- There is a `bytearray` type which enables in-place modification of a string.
+  See [Python Bytearrays](http://stackoverflow.com/a/9099337/175584)
+- Python 3 renames `unicode` to `str` type and byte strings become `bytes` type.
+
+### JavaScript
+
+- Classes should follow the Ext coding style.
+- Class names should be in !CamelCase
+- Instances of classes should use camelCase.
+
+### Path separators
+
+- All relative path separators used within code should be converted to posix
+  format `/`, so should not contain `\` or `\\`. This is to prevent confusion
+  when dealing with cross-platform clients and servers.
+
+### Docstrings
+
+All new docstrings must use Napoleon
+[Google Style](http://www.sphinx-doc.org/en/stable/ext/napoleon.html)
+with old docstrings eventually converted over.
+
+Google Style example:
+
+    def func(arg):
+       """Function purpose.
+
+       Args:
+           arg (type): Description.
+
+       Returns:
+          type: Description. If the line is too, long indent next
+             line with three spaces.
+       """
+       return
+
+See complete list of [supported headers][napoleon sections].
+
+Verify that the documentation parses correctly with:
+
+    python setup.py build_docs
+
+[pre-commit]: http://pre-commit.com/
+[flake8]: https://pypi.python.org/pypi/flake8
+[isort]: https://pypi.python.org/pypi/isort
+[pylint]: http://www.pylint.org/
+[black]: https://github.com/python/black/
+[gtk3 unicode]: http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html
+[napoleon sections]: http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections
diff --git a/docs/source/contributing/documentation.md b/docs/source/contributing/documentation.md
new file mode 100644
index 0000000..cd72b85
--- /dev/null
+++ b/docs/source/contributing/documentation.md
@@ -0,0 +1,14 @@
+# Documentation contributions
+
+## Build
+
+We use Sphinx to create the documentation from source files and docstrings in code.
+
+    pip install -r docs/requirements.txt
+    python setup.py build_docs
+
+The resulting html files are in `docs/build/html`.
+
+## man pages
+
+Located in `docs/man`
diff --git a/docs/source/contributing/index.md b/docs/source/contributing/index.md
new file mode 100644
index 0000000..8c07a76
--- /dev/null
+++ b/docs/source/contributing/index.md
@@ -0,0 +1,13 @@
+# Development & community
+
+Deluge is an open-source project, and relies on its community of users to keep
+getting better.
+
+```{toctree}
+:titlesonly:
+
+code
+testing
+documentation
+translations
+```
diff --git a/docs/source/contributing/testing.md b/docs/source/contributing/testing.md
new file mode 100644
index 0000000..beb30a4
--- /dev/null
+++ b/docs/source/contributing/testing.md
@@ -0,0 +1,50 @@
+# Running tests
+
+Testing uses [PyTest] framework and [PyTest-Twisted] to handle Twisted framework.
+
+## Testing
+
+The tests are located in the source folder under `deluge/tests`.
+The tests are run from the project root directory.
+View the unit test coverage at: [deluge-torrent.github.io](http://deluge-torrent.github.io)
+
+### Pytest
+
+    pytest deluge/tests
+    pytest deluge/tests/test_client.py
+    pytest deluge/tests/test_client.py -k test_connect_localclient
+
+### Plugin
+
+Running the tests for a specific plugin (requires [pytest](https://pypi.python.org/pypi/pytest)):
+
+    pytest deluge/plugins/<name-of-plugin>
+
+## Tox
+
+All the tests for Deluge can be run using [Tox](https://pypi.python.org/pypi/tox)
+
+### See available targets:
+
+    tox -l
+    py3
+    lint
+    docs
+
+### Run specific test:
+
+    tox -e py3
+
+### Verify code with pre-commit:
+
+    tox -e lint
+
+## CI
+
+Deluge develop branch is tested automatically by GitHub actions.
+
+When creating a pull request (PR) on [github], units tests will be automatically be run.
+
+[github]: https://github.com/deluge-torrent/deluge/pulls
+[pytest]: https://docs.pytest.org/en/
+[pytest-twisted]: https://github.com/pytest-dev/pytest-twisted
diff --git a/docs/source/contributing/translations.md b/docs/source/contributing/translations.md
new file mode 100644
index 0000000..fa32d82
--- /dev/null
+++ b/docs/source/contributing/translations.md
@@ -0,0 +1,66 @@
+# Translation contributions
+
+## Translators
+
+For translators we have a [Launchpad translations] account where you can
+translate the `.po` files.
+
+## Marking text for translation
+
+To mark text for translation in Python and ExtJS wrap the string with the
+function `_()` like this:
+
+    torrent.set_tracker_status(_("Announce OK"))
+
+For GTK the text can also be marked translatable in the `glade/*.ui` files:
+
+    <property name="label" translatable="yes">Max Upload Speed:</property>
+
+For more details see: [Python Gettext]
+
+## Translation process
+
+These are the overall stages in gettext translation:
+
+`Portable Object Template -> Portable Object -> Machine Object`
+
+- The `deluge.pot` is created using `generate_pot.py`.
+- Upload `deluge/i18n/deluge.pot` to [Launchpad translations].
+- Give the translators time to translate the text.
+- Download the updated `.po` files from translation site.
+- Extract to `deluge/i18n/` and strip the `deluge-` prefix:
+
+       rename -f 's/^deluge-//' deluge-*.po
+
+- The binary `MO` files for each language are generated by `setup.py`
+  using the `msgfmt.py` script.
+
+To enable Web UI to use translations update `gettext.js` by running `gen_gettext.py` script.
+
+## Useful applications
+
+- [podiff](http://puszcza.gnu.org.ua/projects/podiff/) - Compare textual information in two PO files
+- [gtranslator](http://projects.gnome.org/gtranslator/) - GUI PO file editor
+- [Poedit](http://www.poedit.net/) - GUI PO file editor
+
+## Testing translation
+
+Testing that translations are working correctly can be performed by running
+Deluge as follows.
+
+Create an `MO` for a single language in the correct sub-directory:
+
+    mkdir -p deluge/i18n/fr/LC_MESSAGES
+    python msgfmt.py -o deluge/i18n/fr/LC_MESSAGES/deluge.mo deluge/i18n/fr.po
+
+Run Deluge using an alternative language:
+
+    LANGUAGE=fr deluge
+    LANGUAGE=ru_RU.UTF-8 deluge
+
+Note: If you do not have a particular language installed on your system it
+will only translate based on the `MO` files for Deluge so some GTK
+text/button strings will remain in English.
+
+[launchpad translations]: https://translations.launchpad.net/deluge/
+[python gettext]: http://docs.python.org/library/gettext.html
diff --git a/docs/source/depends.md b/docs/source/depends.md
new file mode 120000
index 0000000..974bd08
--- /dev/null
+++ b/docs/source/depends.md
@@ -0,0 +1 @@
+../../DEPENDS.md
\ No newline at end of file
diff --git a/docs/source/devguide/how-to/curl-jsonrpc.md b/docs/source/devguide/how-to/curl-jsonrpc.md
new file mode 100644
index 0000000..9bb559d
--- /dev/null
+++ b/docs/source/devguide/how-to/curl-jsonrpc.md
@@ -0,0 +1,162 @@
+# How to connect to JSON-RPC with curl
+
+Before continuing make sure `deluge-web` or Web UI plugin is running.
+
+## Create a curl configuration file
+
+To save a lot of typing and to keep the curl command short we shall create
+a `curl.cfg` files and put the following contents in it:
+
+    request = "POST"
+    compressed
+    cookie = "cookie_deluge.txt"
+    cookie-jar = "cookie_deluge.txt"
+    header = "Content-Type: application/json"
+    header = "Accept: application/json"
+    url = "http://localhost:8112/json"
+    write-out = "\n"
+
+To pretty-print the JSON result see: <https://stackoverflow.com/q/352098/175584>
+
+## Log in to Web UI
+
+Log in to the Web UI and get session cookie:
+
+    curl -d '{"method": "auth.login", "params": ["deluge"], "id": 1}' -K curl.cfg
+
+Result is `true` to signify that login was successful:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": true
+    }
+
+Check the contents of the cookie file to verify session ID created.
+
+    cat cookie_deluge.txt
+    # Netscape HTTP Cookie File
+    # http://curl.haxx.se/docs/http-cookies.html
+    # This file was generated by libcurl! Edit at your own risk.
+
+    localhost	FALSE	/json	FALSE	1540061203	_session_id	<session_id>
+
+## Check connected to deluged
+
+Use the `web.connected` method to get a boolean response if the Web UI is
+connected to a deluged host:
+
+    curl -d '{"method": "web.connected", "params": [], "id": 1}' -K curl.cfg
+
+Result is `false` because Web UI is not yet connected to the daemon:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": false
+    }
+
+## Get list of deluged hosts
+
+Use the `web.get_hosts` method:
+
+    curl -d '{"method": "web.get_hosts", "params": [], "id": 1}' -K curl.cfg
+
+The result contains the `<hostID>` for using in request `params` field.
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            [
+                "<hostID>",
+                "127.0.0.1",
+                58846,
+                "localclient"
+            ]
+        ]
+    }
+
+## Get the deluged host status
+
+    curl -d '{"method": "web.get_host_status", \
+    "params": ["<hostID>"], "id": 1}' -K curl.cfg
+
+The result shows the version and status; _online_, _offline_ or _connected_.
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            "<hostID>",
+            "Online",
+            "2.0.0"
+        ]
+    }
+
+## Connect to deluged host
+
+To connect to deluged with `<hostID>`:
+
+    curl -d '{"method": "web.connect", \
+    "params": ["<hostID>"], "id": 1}' -K curl.cfg
+
+The result contains the full list of available host methods:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": [
+            "core.add_torrent_url",
+            ...
+            "core.upload_plugin"
+        ]
+    }
+
+## Disconnect from host
+
+    curl -d '{"method": "web.disconnect", "params": [], "id": 1}' -K curl.cfg
+
+A successful result:
+
+    {
+        "error": null,
+        "id": 1,
+        "result": "Connection was closed cleanly."
+    }
+
+## Add a torrent
+
+    curl -d '{"method": "web.add_torrents", "params": \
+    [[{"path":"/tmp/ubuntu-12.04.1-desktop-amd64.iso.torrent", \
+    "options":null}]], "id": 1}' -K curl.cfg
+
+## Add a magnet URI
+
+    curl-d '{"method": "core.add_torrent_magnet", \
+    "params": ["<magnet_uri>", {}], "id": 1}' -K curl.cfg
+
+## Get list of files for a torrent
+
+    curl -d '{"method": "web.get_torrent_files", \
+    "params": ["<torrentid>"], "id": 1}' -K curl.cfg
+
+## Set a core config option
+
+    curl -d '{"method": "core.set_config", \
+    "params":[{"max_upload_slots_global":"200"}], "id": 1}' -K curl.cfg
+
+    {"error": null, "result": null, "id": 1}
+
+## Useful curl configuration options
+
+For full list of options see man page `man curl` or help `curl --help`:
+
+    --cookie (-b) # Load cookie file with session id
+    --cookie-jar (-c) # Save cookie file with session id
+    --compressed # responses are gzipped
+    --include (-i) # Include the HTTP header in output (optional)
+    --header (-H) # HTTP header
+    --request (-X) # custom request method
+    --data (-d) # data to send in POST request '{"method": "", "params": [], "id": ""}'
+    --insecure (-k) # use with self-signed certs https
diff --git a/docs/source/devguide/how-to/index.md b/docs/source/devguide/how-to/index.md
new file mode 100644
index 0000000..e63c771
--- /dev/null
+++ b/docs/source/devguide/how-to/index.md
@@ -0,0 +1,23 @@
+# How-to guides
+
+A collection of guides for specific issues or to cover more detail than the tutorials.
+
+## Web JSON-RPC
+
+```{toctree}
+:titlesonly:
+
+Connect to JSON-RPC using curl <curl-jsonrpc>
+```
+
+## Plugins
+
+<!--
+- [Create a plugin](create-plugin.md)
+-->
+
+```{toctree}
+:titlesonly:
+
+Update 1.3 plugin for 2.0 <update-1.3-plugin>
+```
diff --git a/docs/source/devguide/how-to/update-1.3-plugin.md b/docs/source/devguide/how-to/update-1.3-plugin.md
new file mode 100644
index 0000000..9ce6ae1
--- /dev/null
+++ b/docs/source/devguide/how-to/update-1.3-plugin.md
@@ -0,0 +1,160 @@
+# How to update a Deluge 1.3 plugin for 2.0
+
+With the new code in Deluge 2.0 there are changes that require authors of
+existing plugins to update their plugins to work on Deluge 2.0.
+
+The main changes are with Python 3 support and the new GTK3 user interface with
+the dropping of GTK2. However it is still possible for a 1.3 plugin to be made
+compatible with 2.0 and this guide aims to helps with that process.
+
+## Python
+
+### Python version matching
+
+Ensure your code is Python >=3.6 compatible.
+
+In `1.3-stable` the plugins that were built with a specific version of Python
+would only be loaded if the system Python also matched.
+
+This has change in Deluge 2.0 and it will load any Python version of plugin
+eggs so compatibility is essential for end-users not to encounter issues.
+
+## GTK 3 addition
+
+In order to support both Deluge 1.3 and 2.0 all existing plugin GTK UI files
+must be copied and then converted to contain only GTK3 code with the old files
+still using PyGTK e.g.:
+
+    cp gtkui.py gtk3ui.py
+
+### Convert from libglade to GtkBuilder
+
+With PyGTK there were two library options for creating the user interface from
+XML files by default Deluge plugins used libglade but that has been deprecated
+and removed in GTK3. So the libglade `.glade` files will need converted to
+GtkBuilder `.ui` files and the Python code updated.
+
+See the official [Migrating to GtkBuilder][migrate-gtkbuilder] document for more details.
+
+#### GtkBuilder conversion script
+
+Install the `gtk-builder-convert` converter on Ubuntu with:
+
+    sudo apt install libgtk2.0-dev
+
+To convert your GTK run it like so:
+
+    gtk-builder-convert data/config.glade data/config.ui
+
+#### Glade UI designer for GTK2
+
+The above conversion can also be done in Glade UI designer (version <=3.8).
+
+In the preferences select `GtkBuilder` as the project file format. Ensure
+that the minimum Gtk version is set to 2.24 and fix any deprecated widgets.
+
+The updated file should be saved with file extension `.ui`.
+
+#### Python code changes
+
+The code needs to replace `gtk.glade` references with `gtk.Builder` and the
+first step is updating how the files are loaded:
+
+```diff
+- glade = gtk.glade.XML(get_resource("config.glade"))
++ builder = Gtk.Builder.new_from_file(get_resource("config.ui"))
+```
+
+Replace signals method:
+
+```diff
+- glade.signal_autoconnect(self)
++ builder.connect_signals(self)
+```
+
+Replace `get_widget` with `get_object`:
+
+```diff
+- glade.get_widget
++ builder.get_object
+```
+
+Check for any remaining `glade` methods and replace with the `builder` equivalents.
+
+### Migrate XML files to GTK3
+
+If you open and save the file it will update with the new requirement header:
+
+    <!-- Generated with glade 3.18.3 -->
+    <interface>
+      <requires lib="gtk+" version="3.10"/>
+
+You can fix deprecated widgets but keep the minimum GTK version to <= 3.10 for
+desktop compatibility.
+
+An example of migrating a Deluge plugin to GtkBuilder: [AutoAdd GtkBuilder]
+
+### Gtk import rename
+
+Move from PyGTK to GTK3 using Python bindings.
+
+<https://pygobject.readthedocs.io/en/latest/guide/porting.html>
+
+    wget https://gitlab.gnome.org/GNOME/pygobject/raw/master/tools/pygi-convert.sh
+    cp gtkui.py gtk3ui.py
+    sh pygi-convert.sh gtk3ui.py
+
+```diff
+-import gtk
++from gi.repository import Gtk
+```
+
+```diff
+- self.builder = gtk.Builder()
++ self.builder = Gtk.Builder()
+```
+
+### Deluge GTK3
+
+#### Imports
+
+Imports will need renamed from `deluge.ui.gtkui` to `deluge.ui.gtk3`.
+
+There is also a new PluginBase for Gtk3 UI:
+
+```diff
+-from deluge.plugins.pluginbase import GtkPluginBase
++from deluge.plugins.pluginbase import Gtk3PluginBase
+-class GtkUI(GtkPluginBase):
++class Gtk3UI(Gtk3PluginBase):
+```
+
+#### Entry points
+
+To enable the GTK3 UI to find the plugin the entry points requires updating too.
+
+In the plugin `__init__.py` file add a new `Gtk3UIPlugin` class:
+
+```
+class Gtk3UIPlugin(PluginInitBase):
+    def __init__(self, plugin_name):
+        from .gtk3ui import Gtk3UI as _plugin_cls
+        self._plugin_cls = _plugin_cls
+        super(Gtk3UIPlugin, self).__init__(plugin_name)
+```
+
+A new entry for GTK3 UI can then be added to `setup.py`:
+
+```diff
+     [deluge.plugin.gtkui]
+     %s = %s:GtkUIPlugin
++    [deluge.plugin.gtk3ui]
++    %s = deluge_%s:Gtk3UIPlugin
+     [deluge.plugin.webui]
+     %s = %s:WebUIPlugin
+-    """ % ((__plugin_name__, __plugin_name__.lower())*3)
++    """ % ((__plugin_name__, __plugin_name__.lower())*4)
+```
+
+[migrate-gtkbuilder]: https://developer.gnome.org/gtk2/stable/gtk-migrating-GtkBuilder.html
+[autoadd gtkbuilder]: https://git.deluge-torrent.org/deluge/commit/?h=develop&id=510a8b50b213cab804d693a5f122f9c0d9dd1fb3
diff --git a/docs/source/devguide/index.md b/docs/source/devguide/index.md
new file mode 100644
index 0000000..436a72a
--- /dev/null
+++ b/docs/source/devguide/index.md
@@ -0,0 +1,13 @@
+# Development guide
+
+This is a guide to help with developing Deluge.
+
+```{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
new file mode 100644
index 0000000..aa7293a
--- /dev/null
+++ b/docs/source/devguide/packaging/index.md
@@ -0,0 +1,9 @@
+# Packaging documentation
+
+```{toctree}
+:titlesonly:
+
+release
+launchpad-recipe
+windows
+```
diff --git a/docs/source/devguide/packaging/launchpad-recipe.md b/docs/source/devguide/packaging/launchpad-recipe.md
new file mode 100644
index 0000000..7d48727
--- /dev/null
+++ b/docs/source/devguide/packaging/launchpad-recipe.md
@@ -0,0 +1,43 @@
+# Launchpad recipe
+
+The launchpad build recipes are for build from source automatically to provide
+Ubuntu packages. They are used to create daily builds of a Deluge git branch.
+
+Note these don't have the same control as a creating a publishing to PPA.
+
+Main reference: <https://help.launchpad.net/Packaging/SourceBuilds/Recipes>
+
+## Deluge Launchpad build recipes
+
+Recipe configuration: <https://code.launchpad.net/~deluge-team/+recipes>
+
+An example for building the develop branch:
+
+    # git-build-recipe format 0.4 deb-version 2.0.0.dev{revno}+{git-commit}+{time}
+    lp:deluge develop
+    nest-part packaging lp:~calumlind/+git/lp_deluge_deb debian debian develop
+
+There are two parts, first to get the source code branch and then the `debian`
+files for building the package.
+
+## Testing and building locally
+
+Create a `deluge.recipe` file with the contents from launchpad and create the
+build files with `git-build-recipe`:
+
+    git-build-recipe --allow-fallback-to-native deluge.recipe lp_build
+
+Setup [pbuilder] and build the deluge package:
+
+    sudo pbuilder build lp_build/deluge*.dsc
+
+Alternatively to build using local files with [pdebuild]:
+
+    cd lp_build/deluge/deluge
+    pdebuild
+
+This will allow modifying the `debian` files to test changes to `rules` or
+`control`.
+
+[pbuilder]: https://wiki.ubuntu.com/PbuilderHowto
+[pdebuild]: https://wiki.ubuntu.com/PbuilderHowto#pdebuild
diff --git a/docs/source/devguide/packaging/release.md b/docs/source/devguide/packaging/release.md
new file mode 100644
index 0000000..e02a09a
--- /dev/null
+++ b/docs/source/devguide/packaging/release.md
@@ -0,0 +1,54 @@
+# Release Checklist
+
+## Pre-release
+
+- Update [translation] `po` files from [Launchpad] account.
+- Changelog is updated with relevant commits and release date is added.
+- Docs [release notes] are updated.
+- Tag release in git and push upstream e.g.
+
+      git tag -a deluge-2.0.0 -m "Deluge 2.0.0 Release"
+
+## Release
+
+- Create source and wheel distributions:
+
+      python setup.py sdist bdist_wheel
+
+- Upload to PyPi (only accepts `tar.gz`):
+
+      twine upload dist/deluge-2.0.0.tar.gz dist/deluge-2.0.0-py3-none-any.whl
+
+- Calculate `sha256sum` for each file e.g.
+
+      cd dist; sha256sum deluge-2.0.0.tar.xz > deluge-2.0.0.tar.xz.sha256
+
+- Upload source tarballs and packages to `ftp-osl.osuosl.org`.
+
+  - Ensure file permissions are global readable: `0644`
+  - Sub-directories correspond to _major.minor_ version e.g. all `2.0.x` patch
+    releases are stored in `source/2.0`.
+  - Change release version in `version*` files, create a new version file for
+    any major releases.
+  - SSH into OSUOSL FTP site and run `trigger-deluge` to sync files.
+
+- Create packages (Ubuntu, Windows, OSX).
+  - Ubuntu: <https://code.launchpad.net/~deluge-team/+recipe/stable-releases>
+    - Ensure launchpad git repo has sync'd to get latest version
+    - Update version in recipe (reset any dash number to 0)
+    - Check for new distribution series needing selected.
+    - Request build for selected series.
+
+## Post-release
+
+- Update with version, hashes and release notes:
+  - Publish new docs version on [ReadTheDocs].
+  - [Wikipedia]
+- Close Trac milestone and add new milestone version for future tickets.
+- Ensure all stable branch commits are also applied to development branch.
+
+[readthedocs]: https://deluge.readthedocs.io
+[wikipedia]: http://en.wikipedia.org/wiki/Deluge_%28software%29
+[launchpad]: https://translations.launchpad.net/deluge
+[translation]: ../../contributing/translations.md
+[release notes]: ../../releases/index.md
diff --git a/docs/source/devguide/packaging/windows.md b/docs/source/devguide/packaging/windows.md
new file mode 100644
index 0000000..253eac0
--- /dev/null
+++ b/docs/source/devguide/packaging/windows.md
@@ -0,0 +1,10 @@
+# Packaging for Windows
+
+Currently there is no working package for Deluge 2.0. The previous Python freezing
+application `bbfreeze` is not compatible with Python 3 and the project is no longer
+maintained.
+
+There are two alternatives `cxfreeze` and `pyinstaller` but neither is trivial with
+the GTKUI application.
+
+See [#3201](https://dev.deluge-torrent.org/ticket/3201)
diff --git a/docs/source/devguide/tutorials/01-setup.md b/docs/source/devguide/tutorials/01-setup.md
new file mode 100644
index 0000000..02195b1
--- /dev/null
+++ b/docs/source/devguide/tutorials/01-setup.md
@@ -0,0 +1,85 @@
+# Setup tutorial for Deluge development
+
+The aim of this tutorial is to download the source code and setup an
+environment to enable development work on Deluge.
+
+## Pre-requisites
+
+To build and run the Deluge applications they depends on tools and libraries as
+listed in DEPENDS.md.
+
+Almost all of the Python packages dependencies will be installed using pip but
+there are some packages or libraries that are required to be installed to the
+system.
+
+### Ubuntu
+
+#### Build tools
+
+    sudo apt install git intltool closure-compiler python3-pip
+    pip3 install --user tox
+
+You might need to add `~/.local/bin` to your PATH.
+
+#### Runtime libraries and tools
+
+    sudo apt install python3-libtorrent python3-geoip python3-dbus  python3-gi \
+    python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3 python3-pygame libnotify4 \
+    librsvg2-common xdg-utils
+
+## Setup development environment
+
+### Clone Deluge git repository
+
+Download the latest git code to local folder.
+
+    git clone git://deluge-torrent.org/deluge.git
+    cd deluge
+
+### Create Python virtual environment
+
+Creation of a [Python virtual environment] keeps the development isolated
+and easier to maintain and Tox has an option to make this process easier:
+
+    tox -e denv
+
+Activate virtual environment:
+
+    source .venv/bin/activate
+
+Deluge will be installed by Tox in _develop_ mode which creates links back
+to source code so that changes will be reflected immediately without repeated
+installation. Check it is installed with:
+
+    (.venv) $ deluge --version
+    deluge-gtk 2.0.0b2.dev149
+    libtorrent: 1.1.9.0
+    Python: 2.7.12
+    OS: Linux Ubuntu 16.04 xenial
+
+### Setup pre-commit hook
+
+Using [pre-commit] ensures submitted code is checked for quality when
+creating git commits.
+
+    (.venv) $ pre-commit install
+
+You are now ready to start playing with the source code.
+
+### Reference
+
+- [Contributing]
+- [Key requirements concepts]
+
+<!--
+## How-to guides
+
+- How to install plugins in develop mode?
+- How to setup and test translations?
+- How to run tests?
+- How to create a plugin?
+-->
+
+[pre-commit]: https://pre-commit.com
+[contributing]: https://dev.deluge-torrent.org/wiki/Contributing
+[requirements topic]: ../topics/requirements.md
diff --git a/docs/source/devguide/tutorials/index.md b/docs/source/devguide/tutorials/index.md
new file mode 100644
index 0000000..2a47252
--- /dev/null
+++ b/docs/source/devguide/tutorials/index.md
@@ -0,0 +1,10 @@
+# Developer tutorials
+
+A list of articles to help developers get started with Deluge.
+
+```{toctree}
+:numbered: 1
+:titlesonly:
+
+Development setup <01-setup>
+```
diff --git a/docs/source/how-to/index.md b/docs/source/how-to/index.md
new file mode 100644
index 0000000..7005a34
--- /dev/null
+++ b/docs/source/how-to/index.md
@@ -0,0 +1,27 @@
+# How-to guides
+
+A collection of guides covering common issues that might be encountered using Deluge.
+
+## GTK UI
+
+```{toctree}
+:titlesonly:
+
+Set default torrent application <set-mime-type>
+```
+
+## Deluge as a service
+
+Services are used to start applications on system boot and leave them running
+in the background. They will also stop the application nicely on system
+shutdown and automatically restart them if they crash.
+
+The Deluge daemon deluged and Web UI deluge-web can both be run as services.
+
+```{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
new file mode 100644
index 0000000..53c21be
--- /dev/null
+++ b/docs/source/how-to/launchd-service.md
@@ -0,0 +1,50 @@
+# How to create launchd services for macOS
+
+The following launchd script uses a separate user deluge, this is optional
+but recommended for security. To create a new deluge user follow the
+​[Apple help] steps.
+
+The paths to `deluged` and `deluge-web` assumes installation using [Homebrew]
+and will need modified if using other installation methods e.g. `Deluge.app`.
+
+## Daemon (deluged) service
+
+Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluged.plist`
+containing the following:
+
+```{eval-rst}
+.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluged.plist
+    :language: xml
+```
+
+Set the service to load on startup and then start it:
+
+```console
+sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluged.plist
+sudo launchctl start org.deluge-torrent.deluged
+```
+
+## Web UI (deluge-web) service
+
+Create the file `/Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist`
+containing the following:
+
+```{eval-rst}
+.. literalinclude:: ../../../packaging/osx/launchd/org.deluge-torrent.deluge-web.plist
+    :language: xml
+```
+
+Set the service to load on startup and then start it:
+
+```console
+sudo launchctl load -w /Library/LaunchDaemons/org.deluge-torrent.deluge-web.plist
+sudo launchctl start org.deluge-torrent.deluge-web
+```
+
+## Logging
+
+Logging is enabled by default in the above script, error level, and can be
+modified as required.
+
+[apple help]: https://support.apple.com/en-gb/guide/mac-help/mtusr001/mac
+[homebrew]: https://brew.sh/
diff --git a/docs/source/how-to/nssm-service.md b/docs/source/how-to/nssm-service.md
new file mode 100644
index 0000000..1e39bf4
--- /dev/null
+++ b/docs/source/how-to/nssm-service.md
@@ -0,0 +1,38 @@
+# How to create NSSM services for Windows
+
+Download ​[NSSM] and read their usage page about installing.
+
+In order for the services to be stopped properly, use the debug application
+versions (ending in `-debug.exe`).
+
+## Daemon (deluged) service
+
+Create a `deluged` service:
+
+```console
+nssm install deluged
+```
+
+The following are minimum UI changes required for the service to work:
+
+```
+Path: C:\Program Files\Deluge\deluged-debug.exe
+Arguments: -c C:\config_location
+```
+
+## Web UI (deluge-web) service
+
+```console
+nssm install deluge-web
+```
+
+```
+Path: C:\Program Files\Deluge\deluge-web-debug.exe
+Arguments: -c C:\config_location
+```
+
+If Web UI is not accessible outside your machine (if you're running
+Deluge from a home server), you have to whitelist Deluge in your Windows
+Firewall for the `deluge-web` and `deluge-web-debug` executable.
+
+[nssm]: http://nssm.cc/
diff --git a/docs/source/how-to/set-mime-type.md b/docs/source/how-to/set-mime-type.md
new file mode 100644
index 0000000..29bad15
--- /dev/null
+++ b/docs/source/how-to/set-mime-type.md
@@ -0,0 +1,24 @@
+# How to set Deluge as default torrent application
+
+## Check registered MIME types
+
+    gio mime application/x-bittorrent
+    gio mime x-scheme-handler/magnet
+
+## Set Deluge as default for MIME types
+
+    gio mime x-scheme-handler/magnet deluge.desktop
+    gio mime application/x-bittorrent deluge.desktop
+
+## Troubleshooting
+
+    update-mime-database ~/.local/share/mime
+    update-desktop-database ~/.local/share/applications
+
+### XDG Check
+
+    xdg-mime query default x-scheme-handler/magnet
+
+## References
+
+<https://help.gnome.org/admin/system-admin-guide/stable/mime-types-custom-user.html.en>
diff --git a/docs/source/how-to/systemd-service.md b/docs/source/how-to/systemd-service.md
new file mode 100644
index 0000000..611ecc1
--- /dev/null
+++ b/docs/source/how-to/systemd-service.md
@@ -0,0 +1,205 @@
+# How to create systemd services for Linux
+
+This guide walks you through setting up Deluge systemd services on Linux.
+
+Ensure Deluge daemon `deluged` and Web UI `deluge-web` are installed. Use
+`which` to check installation paths and if necessary modify the service
+file `ExecStart` lines to point to alternative paths.
+
+## Create a service specific user
+
+For security it is best to run a service with a specific user and group.
+You can create one using the following command:
+
+```console
+sudo adduser --system  --gecos "Deluge Service" --disabled-password --group --home /var/lib/deluge deluge
+```
+
+This creates a new system user and group named `deluge` with no login access
+and home directory `/var/lib/deluge` which will be the default location for the
+config files.
+
+In addition you can add to the `deluge` group any users you wish to be able to
+easily manage or access files downloaded by Deluge, for example:
+
+```console
+sudo adduser <username> deluge
+```
+
+## Daemon (deluged) service
+
+Create the file `/etc/systemd/system/deluged.service` containing the following:
+
+```{eval-rst}
+.. literalinclude:: ../../../packaging/systemd/deluged.service
+    :language: ini
+```
+
+### User configuration
+
+To run the service using the previously created user e.g. `deluge`, first
+create the service configuration directory:
+
+```console
+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}
+.. literalinclude:: ../../../packaging/systemd/user.conf
+    :language: ini
+```
+
+### Start deluged service
+
+Now enable it to start up on boot, start the service and verify it is running:
+
+```console
+sudo systemctl enable /etc/systemd/system/deluged.service
+sudo systemctl start deluged
+sudo systemctl status deluged
+```
+
+### Umask for deluged downloaded files
+
+The `umask` in the service file can be modified to determine access to files
+downloaded by deluged (also applies to logging files). Some useful access
+values are detailed as follows:
+
+- `000` - full access for all users and groups.
+- `007` - only user and group that `deluged` is running as (e.g. `deluge`)
+  with no access from any other accounts.
+- `002` - user and group `deluged` is running as with read-only for all other
+  accounts.
+- `022` - user `deluged` is running as with read-only for all other accounts.
+
+The service for `deluged` must be stopped and started instead of just restarted
+after changes.
+
+## Web UI (deluge-web) service
+
+Create the file `/etc/systemd/system/deluge-web.service` containing the following:
+
+```{eval-rst}
+.. literalinclude:: ../../../packaging/systemd/deluge-web.service
+    :language: ini
+```
+
+### User configuration
+
+To run the service using the previously created user e.g. `deluge`, first
+create the service configuration directory:
+
+```
+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}
+.. literalinclude:: ../../../packaging/systemd/user.conf
+    :language: ini
+```
+
+### Start deluge-web service
+
+Now enable it to start up on boot, start the service and verify it is running:
+
+```console
+sudo systemctl enable /etc/systemd/system/deluge-web.service
+sudo systemctl start deluge-web
+sudo systemctl status deluge-web
+```
+
+## Service logging
+
+Create a log directory for Deluge and give the service user (e.g. `deluge`), full access:
+
+```console
+sudo mkdir -p /var/log/deluge
+sudo chown -R deluge:deluge /var/log/deluge
+sudo chmod -R 750 /var/log/deluge
+```
+
+The deluge log directory is now configured so that user `deluge` has full
+access, group `deluge` read only and everyone else denied access. The `umask`
+specified in the services sets the permission of new log files.
+
+Enable logging in the service files by editing the `ExecStart` line, appending
+`-l` and `-L` options:
+
+```
+ExecStart=/usr/bin/deluged -d -l /var/log/deluge/daemon.log -L warning
+```
+
+```
+ExecStart=/usr/bin/deluge-web -d -l /var/log/deluge/web.log -L warning
+```
+
+See `deluged -h` for all available log-levels.
+
+Restart the services:
+
+```console
+sudo systemctl daemon-reload
+sudo systemctl restart deluged
+sudo systemctl restart deluge-web
+```
+
+### Log rotation
+
+To enable log rotation append `--logrotate` to the above `ExecStart` lines.
+
+## Conditionally start deluged for mount points
+
+If you have a USB disk drive or network drive that may not be immediately
+available on boot or disconnected at random then you may want the `deluged`
+service to wait for mount point to be ready before starting. If they are
+unmounted or disconnected then `deluged` is stopped. When they become available
+again `deluged` is started.
+
+Ensure you have added the correct drive details to `fstab` or equivalent so
+they are mounted at boot.
+
+List the available drive mounts:
+
+```console
+sudo systemctl -t mount
+```
+
+Look for your mount point in the `Description` column. Mounts are formatted
+similar to the mount point with `-`s replacing `/`s in the path.
+e.g.: `media-xyz.mount`
+
+Modify the `[Unit]` section of the `deluged.service` script by adding the
+details below, substituting `xyz.mount` for the mount you want the service
+to depend on:
+
+```ini
+[Unit]
+Description=Deluge Bittorrent Client Daemon
+# Start after network and specified mounts are available.
+After=network-online.target xyz.mount
+Requires=xyz.mount
+# Stops deluged if mount points disconnect
+BindsTo=xyz.mount
+```
+
+For multiple mount points add a space between additional entries. e.g.:
+
+```ini
+After=network-online.target xyz.mount abc.mount def.mount
+```
+
+Modify the `[Install]` section to ensure the deluged service is started when
+the mount point comes back online:
+
+```ini
+[Install]
+WantedBy=multi-user.target xyz.mount
+```
+
+Reference: [systemd.unit](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#RequiresMountsFor=)
diff --git a/docs/source/index.rst b/docs/source/index.rst
new file mode 100644
index 0000000..b46b8f4
--- /dev/null
+++ b/docs/source/index.rst
@@ -0,0 +1,18 @@
+Deluge documentation
+====================
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   Getting started <intro/index.md>
+   How-to guides <how-to/index.md>
+   Release notes <releases/index.md>
+   Contributing <contributing/index.md>
+   Developer guide <devguide/index.md>
+   Reference <reference/index.rst>
+
+* :ref:`genindex`
+* :ref:`modindex`
diff --git a/docs/source/intro/01-install.md b/docs/source/intro/01-install.md
new file mode 100644
index 0000000..15e9945
--- /dev/null
+++ b/docs/source/intro/01-install.md
@@ -0,0 +1,133 @@
+# Installing Deluge
+
+Instructions for installing Deluge.
+
+## <i class="fa fa-linux"></i> Linux
+
+### <i class="icon-ubuntu"></i> Ubuntu
+
+One-click [**Install**](https://tinyurl.com/installdeluge)
+
+```
+sudo apt install deluge
+```
+
+[Package Details](https://packages.ubuntu.com/deluge)
+
+### <i class="icon-fedora"></i> Fedora
+
+```
+sudo dnf install deluge
+```
+
+[Package Details](https://src.fedoraproject.org/rpms/deluge)
+
+### <i class="icon-archlinux"></i> Arch
+
+```
+pacman -S deluge-gtk
+```
+
+[Arch Wiki](https://wiki.archlinux.org/title/Deluge)
+
+### <i class="icon-suse"></i> OpenSUSE
+
+[**1 Click Install**](http://packman.links2linux.org/install/deluge)
+
+[Package Details](https://software.opensuse.org/package/deluge)
+
+### <i class="icon-gentoo"></i> Gentoo
+
+[Package Details](https://packages.gentoo.org/packages/net-p2p/deluge)
+
+### Flatpak
+
+One-click [**Install**](https://dl.flathub.org/repo/appstream/org.deluge_torrent.deluge.flatpakref)
+
+[Package Details](https://flathub.org/apps/details/org.deluge_torrent.deluge)
+
+## <i class="fa fa-windows"></i> Windows
+
+Download [installer](https://ftp.osuosl.org/pub/deluge/windows/?C=M;O=D)
+
+Availble for Windows 7, 8 & 10 for both 32-bit and 64-bit OSes.
+
+## <i class="fa fa-apple"></i> macOS
+
+Unfortunately no official installer package currently available.
+
+See [Alternative Installs](#alternative-installs)
+
+## <i class="icon-freebsd"></i> FreeBSD
+
+```
+pkg add deluge
+```
+
+[Package details](https://www.freshports.org/net-p2p/deluge/)
+
+## <i class="icon-python"></i> PyPi
+
+Install with pip:
+
+    pip install deluge
+
+Install with all [optional dependencies][depends]:
+
+    pip install deluge[all]
+
+Will require system installed packages such as libtorent and GTK3. See [DEPENDS]
+
+e.g. on Ubuntu/Debian install these packages:
+
+    sudo apt install python3-pip python3-libtorrent python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3
+
+## Alternative Installs
+
+### Ubuntu PPA
+
+The [stable PPA] contains the latest releases.
+
+    sudo add-apt-repository -u ppa:deluge-team/stable
+    sudo apt install deluge
+
+The [development PPA] contains daily builds from the `develop` branch.
+
+    sudo add-apt-repository -u ppa:deluge-team/develop
+    sudo apt install deluge
+
+### macOS Community
+
+#### Unofficial `.app` packages
+
+Check sticky topics in [MacOS Forum]
+
+#### Macports
+
+```
+sudo port install deluge
+```
+
+[Package Details](https://ports.macports.org/port/deluge/)
+
+#### Homebrew
+
+1.  Install [Homebrew]
+1.  Open a terminal to install required packages:
+
+        brew install pygobject3 gtk+3 adwaita-icon-theme
+        brew install libtorrent-rasterbar
+
+1.  To fix translations:
+
+        brew link gettext --force
+
+1.  Install Deluge:
+
+        pip install deluge
+
+[development ppa]: https://launchpad.net/~deluge-team/+archive/ubuntu/develop/
+[stable ppa]: https://launchpad.net/~deluge-team/+archive/ubuntu/stable/
+[homebrew]: https://brew.sh/
+[macos forum]: https://forum.deluge-torrent.org/viewforum.php?f=13
+[depends]: ../depends.md
diff --git a/docs/source/intro/index.md b/docs/source/intro/index.md
new file mode 100644
index 0000000..ff0f841
--- /dev/null
+++ b/docs/source/intro/index.md
@@ -0,0 +1,16 @@
+# Getting started with Deluge
+
+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.
+
+```{toctree}
+:numbered: 1
+:titlesonly:
+
+01-install
+```
+
+<!--
+2. Using Deluge
+3. Install a plugin
+-->
diff --git a/docs/source/modules/modules.rst b/docs/source/modules/modules.rst
new file mode 100644
index 0000000..ea1b6e8
--- /dev/null
+++ b/docs/source/modules/modules.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+deluge
+======
+
+
+.. toctree::
+   :maxdepth: 4
+
+   deluge
diff --git a/docs/source/reference/api.rst b/docs/source/reference/api.rst
new file mode 100644
index 0000000..75673af
--- /dev/null
+++ b/docs/source/reference/api.rst
@@ -0,0 +1,14 @@
+Deluge RPC API
+==============
+
+* :doc:`rpc`
+
+.. autoclass:: deluge.core.core.Core
+    :members:
+    :exported:
+    :noindex:
+
+.. autoclass:: deluge.core.daemon.Daemon
+    :members:
+    :exported:
+    :noindex:
diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst
new file mode 100644
index 0000000..a6dea3a
--- /dev/null
+++ b/docs/source/reference/index.rst
@@ -0,0 +1,11 @@
+Reference
+=========
+
+Technical reference material.
+
+.. toctree::
+
+    Web UI <web>
+    Deluge RPC <rpc>
+    RPC API <api>
+    Web API <webapi>
diff --git a/docs/source/reference/rpc.rst b/docs/source/reference/rpc.rst
new file mode 100644
index 0000000..7454bd2
--- /dev/null
+++ b/docs/source/reference/rpc.rst
@@ -0,0 +1,98 @@
+Deluge RPC
+==========
+---------------
+Message Formats
+---------------
+DelugeRPC is a protocol used for daemon/client communication. There are four
+types of messages involved in the protocol: RPC Request, RPC Response,
+RPC Error and Event. All messages are zlib compressed with rencode encoded strings
+and their data formats are detailed below.
+
+"""""""""""
+RPC Request
+"""""""""""
+This message is created and sent by the client to the server requesting that a
+remote method be called. Multiple requests can be bundled in a list.
+
+**[[request_id, method, [args], {kwargs}], ...]**
+
+**request_id** (int)
+    An integer determined by the client that is used in replies from the server.
+    This is used to ensure the client knows which request the data is in
+    response to. Another alternative would be to respond in the same order the
+    requests come in, but this could cause lag if an earlier request takes
+    longer to process.
+
+**method** (str)
+    The name of the remote method to call. This name can be in dotted format to
+    call other objects or plugins methods.
+
+**args** (list)
+    The arguments to call the method with.
+
+**kwargs** (dict)
+    The keyword arguments to call the method with.
+
+""""""""""""
+RPC Response
+""""""""""""
+This message is created and sent in response to a RPC Request from a client. It
+will hold the return value of the requested method call. In the case of an
+error, a RPC Error message will be sent instead.
+
+**[message_type, request_id, [return_value]]**
+
+**message_type** (int)
+    This will be a RPC_RESPONSE type id. This is used on the client side to
+    determine what kind of message is being received from the daemon.
+
+**request_id** (int)
+    The request_id is the same as the one sent by the client in the initial
+    request. It used on the client side to determine what message this is in
+    response to.
+
+**return_value** (list)
+    The return value of the method call.
+
+"""""""""
+RPC Error
+"""""""""
+This message is created in response to an error generated while processing a
+RPC Request and will serve as a replacement for a RPC Response message.
+
+**[message_type, request_id, exception_type, exception_msg, traceback]**
+
+**message_type** (int)
+    This will be a RPC_ERROR type id.
+
+**request_id** (int)
+    The request_id is the same as the one sent by the client in the initial
+    request.
+
+**exception_type** (str)
+    The type of exception raised.
+
+**exception_msg** (str)
+    The message as to why the exception was raised.
+
+**traceback** (str)
+    The traceback of the generated exception.
+
+"""""
+Event
+"""""
+This message is created by the daemon and sent to the clients without being in
+response to a RPC Request. Events are generally sent for changes in the
+daemon's state that the clients need to be made aware of.
+
+**[message_type, event_name, data]**
+
+**message_type** (int)
+    This will be a RPC_EVENT type id.
+
+**event_name** (str)
+    This is the name of the event being emitted by the daemon.
+
+**data** (list)
+    Additional data to be sent with the event. This is dependent upon the event
+    being emitted.
diff --git a/docs/source/reference/web.md b/docs/source/reference/web.md
new file mode 100644
index 0000000..f0471ce
--- /dev/null
+++ b/docs/source/reference/web.md
@@ -0,0 +1,38 @@
+# Deluge Web UI
+
+The Deluge web interface is a full featured interface built using the ExtJS framework,
+running on top of a Twisted web server.
+
+## SSL Configuration
+
+By default the web interface will use the same private key and certificate as
+the Deluge daemon. You can use a different certificate/key and specify it in the Web UI
+config, see below for details.
+
+### Create SSL Certificate Examples
+
+Sample guide: [How to Create a SSL Certificate][ssl cert]
+
+#### Linux
+
+    openssl req -new -x509 -nodes -out deluge.cert.pem -keyout deluge.key.pem
+
+#### Windows
+
+    C:\OpenSSL\bin\openssl.exe req -config C:\OpenSSL\bin\openssl.cnf -x509 -days 365 -newkey rsa:1024 -keyout hostkey.pem -nodes -out hostcert.pem
+
+### Enable Web UI SSL
+
+There are two ways to enable SSL encryption in the web server:
+
+- Specify in your config (accessible via the Preferences window).
+- Use `--ssl` when running the web server, overriding the configuration value to enable SSL.
+
+## Enable Development mode
+
+Append `?dev=true` to the Web UI URL to enable development mode, uses the source
+JavaScript files (if available) rather than compressed versions:
+
+    http://127.0.0.1:8112/?dev=true
+
+[ssl cert]: http://www.yatblog.com/2007/02/27/how-to-create-a-ssl-certificate/
diff --git a/docs/source/reference/webapi.rst b/docs/source/reference/webapi.rst
new file mode 100644
index 0000000..56aadfc
--- /dev/null
+++ b/docs/source/reference/webapi.rst
@@ -0,0 +1,17 @@
+Deluge Web JSON-RPC API
+=======================
+
+* Spec: `JSON-RPC v1 <https://www.jsonrpc.org/specification_v1>`_
+* URL: ``/json``
+* :doc:`api`
+
+
+.. autoclass:: deluge.ui.web.json_api.WebApi
+    :members:
+    :exported:
+    :noindex:
+
+.. autoclass:: deluge.ui.web.json_api.WebUtils
+    :members:
+    :exported:
+    :noindex:
diff --git a/docs/source/releases/2.0.md b/docs/source/releases/2.0.md
new file mode 100644
index 0000000..145171c
--- /dev/null
+++ b/docs/source/releases/2.0.md
@@ -0,0 +1,56 @@
+# Deluge 2.0 release notes
+
+Welcome to the latest release of Deluge, a long time in the making!
+
+## What's new
+
+Some of the highlights since the last major release.
+
+- Migrated to Python 3 with minimal support retained for Python 2.7.
+- Shiny new logo.
+- Multi-user support.
+- Performance updates to handle thousands of torrents with faster loading times.
+- A New Console UI which emulates GTK/Web UIs.
+- GTK UI migrated to GTK3 with UI improvements and additions.
+- Magnet pre-fetching to allow file selection when adding torrent.
+- Fully support libtorrent 1.2 release.
+- Language switching support.
+- Improved documentation hosted on ReadTheDocs.
+- AutoAdd plugin replaces built-in functionality.
+- Web UI now daemonizes by default so service scripts will require `-d` option.
+
+## Packaging
+
+### PyPi
+
+As well as the usual source tarball available for [download] we now have published
+Deluge on the PyPi software repository.
+
+- <https://pypi.org/project/deluge/>
+
+### Windows and MacOS
+
+Unfortunately there are no packages yet for [Windows] or MacOS but they are being worked
+on. For now alternative [install] methods are available for testing.
+
+## Upgrade considerations
+
+Deluge 2.0 is not compatible with Deluge 1.x clients or daemons so these will require
+upgrading too. Also third-party Python scripts may not be compatible if they directly
+connect to the Deluge client and will need migrating.
+
+Always make a backup of your [config] before a major version upgrade to guard against
+data loss.
+
+Translations may not be as up-to date so please help out, see [translations] page.
+
+Plugins written for Deluge 1.3 will need upgrading for Deluge 2.0, due to the
+requirement of Python 3 and GTK3 UI. There is a [update plugin] document to help
+Plugin authors update their plugins.
+
+[update plugin]: ../devguide/how-to/update-1.3-plugin.md
+[windows]: https://dev.deluge-torrent.org/ticket/3201
+[install]: https://deluge.readthedocs.io/en/latest/intro/01-install.html
+[config]: https://dev.deluge-torrent.org/wiki/Faq#WheredoesDelugestoreitssettingsconfig
+[translations]: ../contributing/translations.md
+[download]: http://download.deluge-torrent.org/source/2.0/
diff --git a/docs/source/releases/index.md b/docs/source/releases/index.md
new file mode 100644
index 0000000..69778a0
--- /dev/null
+++ b/docs/source/releases/index.md
@@ -0,0 +1,13 @@
+# Release notes
+
+A summary of the important changes in major releases of Deluge. For more details see
+the [changelog] or the [git commit log].
+
+```{toctree}
+:titlesonly:
+
+../changelog
+2.0
+```
+
+[git commit log]: http://git.deluge-torrent.org/deluge/log/?h=master
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
new file mode 100644
index 0000000..9a841f7
--- /dev/null
+++ b/docs/spelling_wordlist.txt
@@ -0,0 +1,42 @@
+Changelog
+tooltip
+Gtk
+libglade
+Wayland
+macOS
+codebase
+unmanaged
+rebase
+formatter
+camelCase
+docstring
+docstrings
+Pytest
+Tox
+pre
+Blocklist
+boolean
+daemonizes
+daemonize
+config
+Trac
+runtime
+codec
+auth
+hostlist
+hostname
+filesystem
+libtorrent
+Multi
+multi
+username
+whitelist
+systemd
+launchd
+plugin
+plugins
+app
+tarball
+tarballs
+Umask
+online