[Docs] Reorganise and add sections from wiki

- Change the layout and contents of docs to be better organised and
  follow ideas from: https://www.divio.com/blog/documentation/
- Use markdown for non-technical documents to speed up writing.
- Added new sections and imported documents from Trac wiki.

Build fixes:

- Added a patch to fix recommonmark 0.4 and doc referencing:
    https://github.com/rtfd/recommonmark/issues/93
- Set docs build in tox to Py2.7 since there are problems with autodoc
  mocking multiple inheritance on Python 3 resulting in metaclass errors.
- Supressed warning about `modules.rst` not in the toctree by creating
  a static `modules.rst` with `:orphan:` file directive and add to git.
  Also skip creating this toc file with sphinx-apidoc in setup and tox.
- Simplified finding exported RPC and JSON API methods by adding an
  autodoc custom class directive. Removed unneeded __rpcapi.py.

.gitignore

@@ -2,7 +2,7 @@
 build
 .cache
 dist
-docs/source/modules
+docs/source/modules/deluge*.rst
 *egg-info
 *.egg
 *.log

deluge/__rpcapi.py

@@ -1,31 +0,0 @@
-# -*- coding: utf-8 -*-
-#
-# Copyright (C) 2009 Damien Churchill <damoxc@gmail.com>
-#
-# This file is part of Deluge and is licensed under GNU General Public License 3.0, or later, with
-# the additional special exception to link portions of this program with the OpenSSL library.
-# See LICENSE for more details.
-#
-
-from __future__ import unicode_literals
-
-from deluge.core.core import Core
-from deluge.core.daemon import Daemon
-
-
-class RpcApi(object):
-    pass
-
-
-def scan_for_methods(obj):
-    methods = {'__doc__': 'Methods available in %s' % obj.__name__.lower()}
-    for d in dir(obj):
-        if not hasattr(getattr(obj, d), '_rpcserver_export'):
-            continue
-        methods[d] = getattr(obj, d)
-    cobj = type(obj.__name__.lower(), (object,), methods)
-    setattr(RpcApi, obj.__name__.lower(), cobj)
-
-
-scan_for_methods(Core)
-scan_for_methods(Daemon)

deluge/ui/web/json_api.py

@@ -615,6 +615,7 @@ class WebApi(JSONComponent):
 
     @export
     def get_torrent_status(self, torrent_id, keys):
+        """Get the status for a torrent, filtered by status keys."""
         main_deferred = Deferred()
         d = component.get('SessionProxy').get_torrent_status(torrent_id, keys)
         d.addCallback(self._on_torrent_status, main_deferred)
@@ -694,6 +695,7 @@ class WebApi(JSONComponent):
 
     @export
     def get_magnet_info(self, uri):
+        """Parse a magnet URI for hash and name."""
         return get_magnet_info(uri)
 
     @export
@@ -915,14 +917,17 @@ class WebApi(JSONComponent):
 
     @export
     def get_plugin_info(self, name):
+        """Get the details for a plugin."""
         return component.get('Web.PluginManager').get_plugin_info(name)
 
     @export
     def get_plugin_resources(self, name):
+        """Get the resource data files for a plugin."""
         return component.get('Web.PluginManager').get_plugin_resources(name)
 
     @export
     def upload_plugin(self, filename, path):
+        """Upload a plugin to config."""
         main_deferred = Deferred()
 
         shutil.copyfile(path, os.path.join(get_config_dir(), 'plugins', filename))

docs/source/conf.py

@@ -16,13 +16,28 @@ import sys
 from datetime import date
 
 import pkg_resources
+from recommonmark.states import DummyStateMachine
 from recommonmark.transform import AutoStructify
+from sphinx.ext.autodoc import ClassDocumenter, bool_option
 
 try:
     from ...version import get_version
 except ImportError:
     get_version = None
 
+
+# Monkey patch
+class PatchDummyStateMachine(DummyStateMachine):
+    """Fix recommonmark 0.4 doc reference issues."""
+
+    def run_role(self, name, *args, **kwargs):
+        if name == 'doc':
+            name = 'any'
+        return DummyStateMachine.run_role(self, name, *args, **kwargs)
+
+
+DummyStateMachine = PatchDummyStateMachine
+
 # Must add these for autodoc to import packages successully
 __builtin__.__dict__['_'] = lambda x: x
 __builtin__.__dict__['_n'] = lambda s, p, n: s if n == 1 else p
@@ -271,9 +286,18 @@ latex_documents = [
 # If false, no module index is generated.
 # latex_use_modindex = True
 
+# 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
+
 
 def setup(app):
-    app.add_config_value(
-        'recommonmark_config', {'auto_toc_tree_section': 'Contents'}, True
-    )
+    app.connect('autodoc-skip-member', maybe_skip_member)
+    app.add_config_value('recommonmark_config', {}, True)
     app.add_transform(AutoStructify)

docs/source/contributing/code.md

@@ -0,0 +1,115 @@
+# 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.md] 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 formatters
+
+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 formatter.
+
+- Code '''must''' pass [flake8](https://pypi.python.org/pypi/flake8) (w/[https://pypi.python.org/pypi/flake8-quotes flake8-quotes]), [https://pypi.python.org/pypi/isort isort] and [http://www.pylint.org/ Pylint] source code checkers.
+
+  flake8 deluge
+  isort -rc -df deluge
+  pylint deluge
+  pylint deluge/plugins/\*/deluge/
+
+- Using the [http://pre-commit.com/ pre-commit] app can aid in picking up
+  issues before creating git commits.
+
+#### Strings and bytes
+
+To prevent bugs or errors in the code byte strings (`str`) must be decoded to
+strings (unicode strings, `unicode`) on input and then encoded on output.
+
+_Notes:_
+
+- PyGTK/GTK+ will accept `str` (utf8 encoded) or `unicode` but will only return
+  `str`. See [http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html GTK+ 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 [http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections supported headers].
+
+Verify that the documentation parses correctly with:
+
+    python setup.py build_docs

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 requirements-docs.txt
+    python setup.py build_docs
+
+The resulting html files are in `docs/build/html`.
+
+## man pages
+
+Located in `docs/man`

docs/source/contributing/index.md

@@ -0,0 +1,9 @@
+# Development & community
+
+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)

docs/source/contributing/testing.md

@@ -0,0 +1,64 @@
+# Running tests
+
+Deluge testing is implemented using Trial which is Twisted's testing framework
+and an extension of Python's unittest.
+
+See Twisted website for documentation on [Twisted Trial](http://twistedmatrix.com/trac/wiki/TwistedTrial)
+and [Writing tests using Trial](http://twistedmatrix.com/documents/current/core/howto/testing.html).
+
+## 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)
+
+### Trial
+
+Here are some examples that show running all the test through to selecting an
+individual test.
+
+    trial deluge
+    trial deluge.tests.test_client
+    trial deluge.tests.test_client.ClientTestCase
+    trial deluge.tests.test_client.ClientTestCase.test_connect_localclient
+
+### 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
+    py27
+    py3
+    lint
+    docs
+
+#### Run specific test:
+
+    tox -e py3
+
+#### Verify code with pre-commit:
+
+    tox -e lint
+
+## Travis-ci
+
+Deluge develop branch is tested automatically by [Travis].
+When creating a pull request (PR) on [github], Travis will be automatically run
+the unit tests with the code in the PR.
+
+[travis]: https://travis-ci.org/deluge-torrent/deluge
+[github]: https://github.com/deluge-torrent/deluge/pulls

docs/source/contributing/translations.md

@@ -0,0 +1,65 @@
+# 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: [http://docs.python.org/library/gettext.html 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 WebUI 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/

docs/source/core/index.rst

@@ -1,6 +0,0 @@
-The Deluge Core
-===============
-
-.. toctree::
-
-    DelugeRPC <rpc>

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 webui plugin is running.
+
+## Create a curl config
+
+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
+
+## Login to WebUI
+
+Login to the WebUI 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 webui is
+connected to a deluged host:
+
+    curl -d '{"method": "web.connected", "params": [], "id": 1}' -K curl.cfg
+
+Result is `false` because WebUI 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 avaiable 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 config 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

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

@@ -0,0 +1,8 @@
+# How-to guides
+
+This is a collection of guides for specific issues or cover more details than
+the tutorials.
+
+## Web JSON-RPC
+
+- [Connect to JSON-RPC using curl](curl-jsonrpc.md)

docs/source/devguide/index.md

@@ -0,0 +1,7 @@
+# Deluge Development Guide
+
+This is a guide to help with developing Deluge.
+
+- [Tutorials](tutorials/index.md)
+- [How-to](how-to/index.md)
+- [Packaging](packaging/index.md)

docs/source/devguide/packaging/index.md

@@ -0,0 +1,4 @@
+# Packaging documentation
+
+- [Release checklist](release.md)
+- [Launchpad recipe](launchpad-recipe.md)

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 git repo 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

docs/source/devguide/packaging/release.md

@@ -0,0 +1,37 @@
+# Release Checklist
+
+## Pre-Release
+
+- Update [translation](../contributing/translations.md) `po` files from
+  [Launchpad](https://translations.launchpad.net/deluge) account.
+- Changelog is updated with relevant commits and release date is added.
+- Version number increment:
+  - setup.py
+  - man pages
+  - osx/Info.plist
+  - Version and month `sed` commands:
+    - `git grep -l '2\.0\.0' | grep -v CHANGELOG.md | xargs sed -i 's/2\.0\.0/2\.0\.1/g'`
+    - `git grep -l 'October' docs/man | xargs sed -i 's/October/November/g'`
+- Increment copyright year:
+  - osx/Info.plist
+- Tag release in git and push upstream.
+  - e.g. `git tag -a deluge-2.0.0 -m "Deluge 2.0.0 Release"`
+
+## Release
+
+- Run `make_release` script on extracted tarball e.g.
+  - `make_release deluge-2.0.0`
+- Package for OSs, Ubuntu, Windows, OSX.
+- Upload source tarballs and packages to ftp.
+  (_Ensure file permissions are global readable:_ `0644`)
+
+## Post-Release
+
+- Update with version, hashes and release notes:
+  - ReleaseNotes (Create new version page and add link to this page)
+  - Forum announcement
+  - IRC welcome message
+  - Website `index.php` and `version` files
+  - [Wikipedia](http://en.wikipedia.org/wiki/Deluge_%28software%29)
+- Trac close the milestone and add new version for tickets.
+- Ensure all stable branch commits are also applied to development branch.

docs/source/devguide/tutorials/01-setup.md

@@ -0,0 +1,82 @@
+# 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
+    pip install --user tox tox-venv
+
+#### Runtime libraries and tools
+
+    sudo apt install python-libtorrent python-geoip python-dbus python-glade2 \
+    librsvg2-common xdg-utils python-appindicator python-notify python-pygame
+
+## 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 denv3
+
+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

docs/source/devguide/tutorials/index.md

@@ -0,0 +1,5 @@
+# Developer tutorials
+
+A list of articles to help developers get started with Deluge.
+
+- [Development setup](01-setup.md)

docs/source/index.rst

@@ -1,30 +1,15 @@
-.. deluge documentation master file, created by sphinx-quickstart on Tue Nov  4 18:24:06 2008.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Deluge Documentation
+====================
 
-Welcome to Deluge's Documentation!
-==================================
-
-Contents:
+Contents
+--------
 
 .. toctree::
    :maxdepth: 2
 
-   Core <core/index.rst>
-   Interfaces <interfaces/index.rst>
-
-Indices and tables
-==================
+   Contributing <contributing/index.md>
+   Developer Guide <devguide/index.md>
+   Reference <reference/index.rst>
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
-Modules
-=======
-
-.. toctree::
-   :maxdepth: 2
-   :glob:
-
-   modules/*

docs/source/interfaces/console.rst

@@ -1,2 +0,0 @@
-Deluge Console UI
-=================

docs/source/interfaces/gtk.rst

@@ -1,2 +0,0 @@
-Deluge GTK UI
-=============

docs/source/interfaces/index.rst

@@ -1,10 +0,0 @@
-Deluge's Interfaces
-===================
-
-Interfaces.
-
-.. toctree::
-
-    Gtk Interface <gtk>
-    Web Interface <web>
-    Console Interface <console>

docs/source/modules/modules.rst

@@ -0,0 +1,10 @@
+:orphan:
+
+deluge
+======
+
+
+.. toctree::
+   :maxdepth: 4
+
+   deluge

docs/source/reference/api.rst

@@ -0,0 +1,12 @@
+Deluge RPC API
+==============
+
+* :doc:`rpc`
+
+.. autoclass:: deluge.core.core.Core
+    :members:
+    :exported:
+
+.. autoclass:: deluge.core.daemon.Daemon
+    :members:
+    :exported:

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>

docs/source/reference/rpc.rst

@@ -96,10 +96,3 @@ daemon's state that the clients need to be made aware of.
 **data** (list)
     Additional data to be sent with the event. This is dependent upon the event
     being emitted.
-
-----------
-Remote API
-----------
-
-.. autoclass:: deluge.__rpcapi.RpcApi
-    :members:

docs/source/reference/web.md

@@ -1,16 +1,13 @@
-Deluge Web UI
-=============
+# Deluge Web UI
 
 The Deluge web interface is intended to be a full featured interface built using
 the ExtJS framework, running on top of a Twisted webserver.
 
+## SSL Configuration
 
-=================
-SSL Configuration
-=================
 By default the web interface will use the same private key and certificate as
 the Deluge daemon. If you wish to use a different certificate/key (see
-`How to Create a SSL Certificate <http://www.yatblog.com/2007/02/27/how-to-create-a-ssl-certificate/>`_
+[How to Create a SSL Certificate](http://www.yatblog.com/2007/02/27/how-to-create-a-ssl-certificate/))
 for information on creating one) you are able to specify which you want to use.
 
 There are 2 ways to enable SSL encryption in the webserver, 1 is to specify it

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:

setup.cfg

@@ -24,7 +24,8 @@ known_third_party =
 # Ignore gtk modules, primarily for tox testing.
     pygtk, gtk, gobject, gtk.gdk, pango, cairo, pangocairo,
 # Ignore other module dependencies for pre-commit isort.
-    twisted, OpenSSL, pytest, recommonmark, chardet, pkg_resources, zope, mock
+    twisted, OpenSSL, pytest, recommonmark, chardet, pkg_resources, zope, mock,
+    sphinx
 known_first_party = msgfmt, deluge
 order_by_type = true
 not_skip = __init__.py

setup.py

@@ -77,12 +77,15 @@ class BuildDocs(BuildDoc):
 
     def run(self):
         print('Generating module documentation...')
-        os.system('sphinx-apidoc --force -o docs/source/modules/ deluge deluge/plugins')
+        os.system(
+            'sphinx-apidoc --force --no-toc'
+            ' -o docs/source/modules/ deluge deluge/plugins'
+        )
         BuildDoc.run(self)
 
 
 class CleanDocs(cmd.Command):
-    description = 'Clean the documentation build and rst files'
+    description = 'Clean the documentation build and module rst files'
     user_options = []
 
     def initialize_options(self):
@@ -92,12 +95,15 @@ class CleanDocs(cmd.Command):
         pass
 
     def run(self):
-        for docs_dir in ('docs/build', 'docs/source/modules'):
-            try:
-                print('Deleting {}'.format(docs_dir))
-                rmtree(docs_dir)
-            except OSError:
-                pass
+        docs_build = 'docs/build'
+        print('Deleting {}'.format(docs_build))
+        try:
+            rmtree(docs_build)
+        except OSError:
+            pass
+
+        for module in glob.glob('docs/source/modules/deluge*.rst'):
+            os.remove(module)
 
 
 class BuildWebUI(cmd.Command):

tox.ini

@@ -154,14 +154,16 @@ deps =
     -rrequirements-docs.txt
 
 [testenv:docs]
+basepython = python2.7
 sitepackages = {[docsbase]sitepackages}
 deps = {[docsbase]deps}
 commands =
     python setup.py clean_docs
-    sphinx-apidoc --force -o docs/source/modules/ deluge deluge/plugins
+    sphinx-apidoc --force --no-toc -o docs/source/modules/ deluge deluge/plugins
     sphinx-build -v -j auto -E -T -b html -d docs/build/doctrees docs/source docs/build/html
 
 [testenv:docscoverage]
+basepython = python2.7
 sitepackages = {[docsbase]sitepackages}
 changedir = {[docsbase]changedir}
 deps =
@@ -175,7 +177,7 @@ commands =
 
 
 # ========================
-# Developement Environment
+# Development Environment
 # ========================
 [basedev]
 usedevelop = True