mirror of
https://github.com/logos-storage/deluge.git
synced 2026-08-26 02:11:16 +00:00
[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.
This commit is contained in:
Calum Lind
@@ -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
|
||||
@@ -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)
|
||||
@@ -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)
|
||||
@@ -0,0 +1,4 @@
|
||||
# Packaging documentation
|
||||
|
||||
- [Release checklist](release.md)
|
||||
- [Launchpad recipe](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
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -0,0 +1,5 @@
|
||||
# Developer tutorials
|
||||
|
||||
A list of articles to help developers get started with Deluge.
|
||||
|
||||
- [Development setup](01-setup.md)
|
||||
Reference in New Issue
Block a user