diff --git a/.gitignore b/.gitignore index a527a0a01f..04aa1da7b0 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ build .cache dist -docs/source/modules +docs/source/modules/deluge*.rst *egg-info *.egg *.log diff --git a/deluge/__rpcapi.py b/deluge/__rpcapi.py deleted file mode 100644 index b279d23ea1..0000000000 --- a/deluge/__rpcapi.py +++ /dev/null @@ -1,31 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Copyright (C) 2009 Damien Churchill -# -# 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) diff --git a/deluge/ui/web/json_api.py b/deluge/ui/web/json_api.py index 2ea0e493cb..536a3408c0 100644 --- a/deluge/ui/web/json_api.py +++ b/deluge/ui/web/json_api.py @@ -615,6 +615,7 @@ def _on_torrent_status(self, torrent, d): @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 @@ def get_torrent_info(self, filename): @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 @@ def get_plugins(self): @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)) diff --git a/docs/source/conf.py b/docs/source/conf.py index d24ccf8dba..4d70c35bd1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,13 +16,28 @@ 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 @@ def __or__(self, __): # 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) diff --git a/docs/source/contributing/code.md b/docs/source/contributing/code.md new file mode 100644 index 0000000000..9fdf854252 --- /dev/null +++ b/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 diff --git a/docs/source/contributing/documentation.md b/docs/source/contributing/documentation.md new file mode 100644 index 0000000000..a994c5aa46 --- /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 requirements-docs.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 0000000000..afdead24de --- /dev/null +++ b/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) diff --git a/docs/source/contributing/testing.md b/docs/source/contributing/testing.md new file mode 100644 index 0000000000..b77cf51280 --- /dev/null +++ b/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/ + +## 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 diff --git a/docs/source/contributing/translations.md b/docs/source/contributing/translations.md new file mode 100644 index 0000000000..bbb36bb9db --- /dev/null +++ b/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: + + Max Upload Speed: + +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/ diff --git a/docs/source/core/index.rst b/docs/source/core/index.rst deleted file mode 100644 index ac0760dc8e..0000000000 --- a/docs/source/core/index.rst +++ /dev/null @@ -1,6 +0,0 @@ -The Deluge Core -=============== - -.. toctree:: - - DelugeRPC 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 0000000000..a890911417 --- /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 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 + +## 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 `` for using in request `params` field. + + { + "error": null, + "id": 1, + "result": [ + [ + "", + "127.0.0.1", + 58846, + "localclient" + ] + ] + } + +## Get the deluged host status + + curl -d '{"method": "web.get_host_status", \ + "params": [""], "id": 1}' -K curl.cfg + +The result shows the version and status; _online_, _offline_ or _connected_. + + { + "error": null, + "id": 1, + "result": [ + "", + "Online", + "2.0.0" + ] + } + +## Connect to deluged host + +To connect to deluged with ``: + + curl -d '{"method": "web.connect", \ + "params": [""], "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": ["", {}], "id": 1}' -K curl.cfg + +## Get list of files for a torrent + + curl -d '{"method": "web.get_torrent_files", \ + "params": [""], "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 diff --git a/docs/source/devguide/how-to/index.md b/docs/source/devguide/how-to/index.md new file mode 100644 index 0000000000..da978c16b8 --- /dev/null +++ b/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) diff --git a/docs/source/devguide/index.md b/docs/source/devguide/index.md new file mode 100644 index 0000000000..136993ade6 --- /dev/null +++ b/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) diff --git a/docs/source/devguide/packaging/index.md b/docs/source/devguide/packaging/index.md new file mode 100644 index 0000000000..979679141e --- /dev/null +++ b/docs/source/devguide/packaging/index.md @@ -0,0 +1,4 @@ +# Packaging documentation + +- [Release checklist](release.md) +- [Launchpad recipe](launchpad-recipe.md) diff --git a/docs/source/devguide/packaging/launchpad-recipe.md b/docs/source/devguide/packaging/launchpad-recipe.md new file mode 100644 index 0000000000..7494cb9345 --- /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 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 diff --git a/docs/source/devguide/packaging/release.md b/docs/source/devguide/packaging/release.md new file mode 100644 index 0000000000..4ecb938729 --- /dev/null +++ b/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. diff --git a/docs/source/devguide/tutorials/01-setup.md b/docs/source/devguide/tutorials/01-setup.md new file mode 100644 index 0000000000..c993b3c0fa --- /dev/null +++ b/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] + + + +[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 0000000000..36a8abf841 --- /dev/null +++ b/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) diff --git a/docs/source/index.rst b/docs/source/index.rst index 76f46180d4..828252d9bb 100644 --- a/docs/source/index.rst +++ b/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 - Interfaces - -Indices and tables -================== + Contributing + Developer Guide + Reference * :ref:`genindex` * :ref:`modindex` -* :ref:`search` - -Modules -======= - -.. toctree:: - :maxdepth: 2 - :glob: - - modules/* diff --git a/docs/source/interfaces/console.rst b/docs/source/interfaces/console.rst deleted file mode 100644 index 176d17ead2..0000000000 --- a/docs/source/interfaces/console.rst +++ /dev/null @@ -1,2 +0,0 @@ -Deluge Console UI -================= diff --git a/docs/source/interfaces/gtk.rst b/docs/source/interfaces/gtk.rst deleted file mode 100644 index f8d315fe22..0000000000 --- a/docs/source/interfaces/gtk.rst +++ /dev/null @@ -1,2 +0,0 @@ -Deluge GTK UI -============= diff --git a/docs/source/interfaces/index.rst b/docs/source/interfaces/index.rst deleted file mode 100644 index ac946cf5f4..0000000000 --- a/docs/source/interfaces/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -Deluge's Interfaces -=================== - -Interfaces. - -.. toctree:: - - Gtk Interface - Web Interface - Console Interface diff --git a/docs/source/modules/modules.rst b/docs/source/modules/modules.rst new file mode 100644 index 0000000000..ea1b6e8be5 --- /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 0000000000..62fe4c46f5 --- /dev/null +++ b/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: diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst new file mode 100644 index 0000000000..a6dea3aee4 --- /dev/null +++ b/docs/source/reference/index.rst @@ -0,0 +1,11 @@ +Reference +========= + +Technical reference material. + +.. toctree:: + + Web UI + Deluge RPC + RPC API + Web API diff --git a/docs/source/core/rpc.rst b/docs/source/reference/rpc.rst similarity index 97% rename from docs/source/core/rpc.rst rename to docs/source/reference/rpc.rst index 817e015715..95b5ecbee2 100644 --- a/docs/source/core/rpc.rst +++ b/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: diff --git a/docs/source/interfaces/web.rst b/docs/source/reference/web.md similarity index 77% rename from docs/source/interfaces/web.rst rename to docs/source/reference/web.md index 77e73195f4..eb2d3747dd 100644 --- a/docs/source/interfaces/web.rst +++ b/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 `_ +[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 diff --git a/docs/source/reference/webapi.rst b/docs/source/reference/webapi.rst new file mode 100644 index 0000000000..56aadfc2f9 --- /dev/null +++ b/docs/source/reference/webapi.rst @@ -0,0 +1,17 @@ +Deluge Web JSON-RPC API +======================= + +* Spec: `JSON-RPC 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/setup.cfg b/setup.cfg index 8229586027..521a15dd2d 100644 --- a/setup.cfg +++ b/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 diff --git a/setup.py b/setup.py index 04bd604b70..b2ebf148fd 100755 --- a/setup.py +++ b/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 @@ def finalize_options(self): 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): diff --git a/tox.ini b/tox.ini index 564b336794..bb6b096a5c 100644 --- a/tox.ini +++ b/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