diff options
Diffstat (limited to '')
41 files changed, 2319 insertions, 0 deletions
diff --git a/docs/man/deluge-console.1 b/docs/man/deluge-console.1 new file mode 100644 index 0000000..edffba5 --- /dev/null +++ b/docs/man/deluge-console.1 @@ -0,0 +1,100 @@ +.TH DELUGE-CONSOLE 1 + +.SH NAME +deluge-console - A BitTorrent client console interface + +.SH SYNOPSIS +.B deluge-console [options] + +.SH DESCRIPTION +Deluge utilizes a client/server model, with \fBdeluged\fR being the daemon process and \fBdeluge-console\fR being used to launch a curses console user-interface. +.P +.SS Console Commands: +You can pass console commands directly from the command line and use semi-colon (\fB;\fR) separator to run multiple commands. Enclosing the commands with quotes may also be required +for example: + + \fBdeluge-console 'add <torrent>; info <torrent_id>'\fR + +The following console commands are available: +.TS +tab (@); +lB lx. +add@Add torrents +cache@Show information about the disk cache +config@Show and set configuration values +connect@Connect to a new deluge server +debug@Enable and disable debugging +del@Alias for \fBrm\fR +exit@Alias for \fBquit\fR +gui@Enable interactive mode +halt@Shutdown the deluge server +help@Displays help on other commands +info@Show information about the torrents +manage@Show and manage per-torrent options +move@Move torrents' storage location +pause@Pause torrents +plugin@Manage plugins +quit@Exit the client +reannounce@Alias for \fBupdate_tracker\fR +recheck@Forces a recheck of the torrent data +resume@Resume torrents +rm@Remove a torrent +status@Shows various status information from the daemon +update_tracker@Update tracker for torrent(s) +.TE + +.SH OPTIONS +.SS Config Options +.TP +.BI \-c\ path \fR,\ \fB\-\-config= path +Set the config directory location. + +.SS Console Options +These daemon connect options will be used for commands, or if console ui autoconnect is enabled. +.TP +.BI \-d\ ip_addr \fR,\ \fB\-\-daemon= ip_addr +Deluge daemon IP address to connect to (default 127.0.0.1) +.TP +.BI \-p\ port \fR,\ \fB\-\-port= port +Deluge daemon port to connect to (default 58846) +.TP +.BI \-U\ user \fR,\ \fB\-\-username= user +Deluge daemon username to use when connecting +.TP +.BI \-P\ pass \fR,\ \fB\-\-password= pass +Deluge daemon password to use when connecting + +.SS Logging Options +.TP +.BI \-l\ file \fR,\ \fB\-\-logfile= file +Output to specified logfile instead of stdout +.TP +.BI \-L\ loglevel \fR,\ \fB\-\-loglevel= loglevel +Set the log level (default is error): +.B none, info, warning, error, debug +.TP +.B \-q\fR,\ \fB\-\-quiet +Sets the log level to \fBnone\fR, same as \fB\-L none +.TP +.BI \-\-logrotate\fR[\fB=\fImax-size\fR] +Enable logfile rotation, with optional maximum logfile +size, default: 2M (Logfile rotation count is 5) +.TP +.BI \-\-profile\fR[\fB=\fIfile\fR] +Profile with cProfile. Outputs to stdout unless a filename is specified + +.SS Help Options +.TP +.B \-V\fR,\ \fB\-\-version +Show program's version number and exit. +.TP +.B \-h\fR,\ \fB\-\-help +Show help message and exit. + +.SH SEE ALSO +.BR deluge (1), +.BR deluged (1), +.BR deluge-web (1) + +.SH AUTHORS +.B Deluge Team: http://www.deluge-torrent.org diff --git a/docs/man/deluge-gtk.1 b/docs/man/deluge-gtk.1 new file mode 100644 index 0000000..a27b0c9 --- /dev/null +++ b/docs/man/deluge-gtk.1 @@ -0,0 +1,55 @@ +.TH DELUGE-GTK 1 + +.SH NAME +deluge-gtk - A BitTorrent client Gtk interface + +.SH SYNOPSIS +.B deluge-gtk [options] +.RI [ torrent-file\fR] + +.SH DESCRIPTION +Deluge utilizes a client/server model, with \fBdeluged\fR being the daemon process and \fBdeluge-gtk\fR being used to launch a Gtk user-interface. +.P +By default, Deluge will run in \fIStandalone\fR mode where the daemon functionality will be hidden. +You can switch to \fIThinclient\fR mode in the Preferences dialog. + +.SH OPTIONS +.SS Config Options +.TP +.BI \-c\ path \fR,\ \fB\-\-config= path +Set the config directory location. + +.SS Logging Options +.TP +.BI \-l\ file \fR,\ \fB\-\-logfile= file +Output to specified logfile instead of stdout +.TP +.BI \-L\ loglevel \fR,\ \fB\-\-loglevel= loglevel +Set the log level (default is error): +.B none, info, warning, error, debug +.TP +.B \-q\fR,\ \fB\-\-quiet +Sets the log level to \fBnone\fR, same as \fB\-L none +.TP +.BI \-\-logrotate\fR[\fB=\fImax-size\fR] +Enable logfile rotation, with optional maximum logfile +size, default: 2M (Logfile rotation count is 5) +.TP +.BI \-\-profile\fR[\fB=\fIfile\fR] +Profile with cProfile. Outputs to stdout unless a filename is specified + +.SS Help Options +.TP +.B \-V\fR,\ \fB\-\-version +Show program's version number and exit. +.TP +.B \-h\fR,\ \fB\-\-help +Show help message and exit. + +.SH SEE ALSO +.BR deluged (1), +.BR deluge-web (1) +.BR deluge-console (1), + +.SH AUTHORS +.B Deluge Team: http://www.deluge-torrent.org diff --git a/docs/man/deluge-web.1 b/docs/man/deluge-web.1 new file mode 100644 index 0000000..f9f83ae --- /dev/null +++ b/docs/man/deluge-web.1 @@ -0,0 +1,86 @@ +.TH DELUGE-WEB 1 + +.SH NAME +deluge-web - A BitTorrent client web interface + +.SH SYNOPSIS +.B deluge-web [options] + +.SH DESCRIPTION +Deluge utilizes a client/server model, with \fBdeluged\fR being the daemon process and \fBdeluge-web\fR being used to launch an ajax web based user-interface. +.P +By default \fBdeluge-web\fR will run as a background daemon, use the \fB\-d\fR option to run process in foreground. + +The default password is \fBdeluge\fR and serves \fBhttp://localhost:8112\fR web page. + +.SH OPTIONS +.SS Config Options +.TP +.BI \-c\ path \fR,\ \fB\-\-config= path +Set the config directory location. + +.SS Web Options +.TP +.BI \-i\ ip_address \fR,\ \fB\-\-interface= ip_address +IP address for web server to listen on +.TP +.BI \-p\ port \fR,\ \fB\-\-port= port +Port for web server to listen on +.TP +.BI \-b\ path \fR,\ \fB\-\-base= path +Set the base path that the web ui is running on (proxying) +.TP +.B \-\-ssl +Forces the webserver to use ssl +.TP +.B \-\-no-ssl +Forces the webserver to disable ssl + +.SS Logging Options +.TP +.BI \-l\ file \fR,\ \fB\-\-logfile= file +Output to specified logfile instead of stdout +.TP +.BI \-L\ loglevel \fR,\ \fB\-\-loglevel= loglevel +Set the log level (default is error): +.B none, info, warning, error, debug +.TP +.B \-q\fR,\ \fB\-\-quiet +Sets the log level to \fBnone\fR, same as \fB\-L none +.TP +.BI \-\-logrotate\fR[\fB=\fImax-size\fR] +Enable logfile rotation, with optional maximum logfile +size, default: 2M (Logfile rotation count is 5) +.TP +.BI \-\-profile\fR[\fB=\fIfile\fR] +Profile with cProfile. Outputs to stdout unless a filename is specified + +.SS Process Control Options: +.TP +.BI \-P\ file \fR,\ \fB\-\-pidfile= file +Pidfile to store the process id +.TP +.B -d\fR,\ \fB\-\-do-not-daemonize +Do not daemonize (fork) this process +.TP +.BI \-U\fR,\ \fB\-\-user= user +Change to this user on startup (Requires root) +.TP +.BI \-g\fR,\ \fB\-\-group= group +Change to this group on startup (Requires root) + +.SS Help Options +.TP +.B \-V\fR,\ \fB\-\-version +Show program's version number and exit. +.TP +.B \-h\fR,\ \fB\-\-help +Show help message and exit. + +.SH SEE ALSO +.BR deluge (1), +.BR deluged (1), +.BR deluge-console (1) + +.SH AUTHORS +.B Deluge Team: http://www.deluge-torrent.org diff --git a/docs/man/deluge.1 b/docs/man/deluge.1 new file mode 100644 index 0000000..19aef4f --- /dev/null +++ b/docs/man/deluge.1 @@ -0,0 +1,63 @@ +.TH DELUGE 1 + +.SH NAME +deluge - A BitTorrent client + +.SH SYNOPSIS +.B deluge [options] +.RI [ torrent-file\fR] + +.SH DESCRIPTION +Deluge utilizes a client/server model, with \fBdeluged\fR being the daemon process and \fBdeluge\fR being used to launch a user-interface. +.P +By default, Deluge will run in \fIStandalone\fR mode where the daemon functionality will be hidden. +You can switch to \fIThinclient\fR mode in the Preferences dialog. + +.SH OPTIONS +.SS Config Options +.TP +.BI \-c\ path \fR,\ \fB\-\-config= path +Set the config directory location. + +.SS UI Options +See \fBdeluge -h\fR for available user interfaces. +.TP +.I user_interface \fR[\fIui-args\fR] Alternative UI to launch, with optional ui args +.TP +.BI -s\ default_ui \fR,\ \fB--set-default-ui= default_ui +Sets the default UI to be run when no UI is specified + +.SS Logging Options +.TP +.BI \-l\ file \fR,\ \fB\-\-logfile= file +Output to specified logfile instead of stdout +.TP +.BI \-L\ loglevel \fR,\ \fB\-\-loglevel= loglevel +Set the log level (default is error): +.B none, info, warning, error, debug +.TP +.B \-q\fR,\ \fB\-\-quiet +Sets the log level to \fBnone\fR, same as \fB\-L none +.TP +.BI \-\-logrotate\fR[\fB=\fImax-size\fR] +Enable logfile rotation, with optional maximum logfile +size, default: 2M (Logfile rotation count is 5) +.TP +.BI \-\-profile\fR[\fB=\fIfile\fR] +Profile with cProfile. Outputs to stdout unless a filename is specified + +.SS Help Options +.TP +.B \-V\fR,\ \fB\-\-version +Show program's version number and exit. +.TP +.B \-h\fR,\ \fB\-\-help +Show help message and exit. + +.SH SEE ALSO +.BR deluged (1), +.BR deluge-web (1) +.BR deluge-console (1), + +.SH AUTHORS +.B Deluge Team: http://www.deluge-torrent.org diff --git a/docs/man/deluged.1 b/docs/man/deluged.1 new file mode 100644 index 0000000..a1877a4 --- /dev/null +++ b/docs/man/deluged.1 @@ -0,0 +1,78 @@ +.TH DELUGED 1 + +.SH NAME +deluged - A BitTorrent client daemon + +.SH SYNOPSIS +.B deluged [options] + +.SH DESCRIPTION +Deluge utilizes a client/server model, with \fBdeluged\fR being the daemon process and \fBdeluge\fR being used to launch a user-interface. +.P +By default \fBdeluged\fR will run as a background daemon, use the \fB\-d\fR option to run process in foreground. + +.SH OPTIONS +.SS Config Options +.TP +.BI \-c\ path ,\ \fB\-\-config= path +Set the config directory location. + +.SS Daemon Options +.TP +.BI -p\ port \fR,\ \fB--port= port +Port daemon will listen on, default is 58846 +.TP +.BI -i\ ip_address \fR,\ \fB--interface= ip_address +Interface daemon will listen for bittorrent connections on, this should be an IP address +.TP +.BI -u\ ip_address \fR,\ \fB--ui-interface= ip_address +Interface daemon will listen for UI connections on, this should be an IP address + +.SS Logging Options +.TP +.BI \-l\ file \fR,\ \fB\-\-logfile= file +Output to specified logfile instead of stdout +.TP +.BI \-L\ loglevel \fR,\ \fB\-\-loglevel= loglevel +Set the log level (default is error): +.B none, info, warning, error, debug +.TP +.B \-q\fR,\ \fB\-\-quiet +Sets the log level to \fBnone\fR, same as \fB\-L none +.TP +.BI \-\-logrotate\fR[\fB=\fImax-size\fR] +Enable logfile rotation, with optional maximum logfile +size, default: 2M (Logfile rotation count is 5) +.TP +.BI \-\-profile\fR[\fB=\fIfile\fR] +Profile with cProfile. Outputs to stdout unless a filename is specified + +.SS Process Control Options: +.TP +.BI \-P\ file \fR,\ \fB\-\-pidfile= file +Pidfile to store the process id +.TP +.B -d\fR,\ \fB\-\-do-not-daemonize +Do not daemonize (fork) this process +.TP +.BI \-U\fR,\ \fB\-\-user= user +Change to this user on startup (Requires root) +.TP +.BI \-g\fR,\ \fB\-\-group= group +Change to this group on startup (Requires root) + +.SS Help Options +.TP +.B \-V\fR,\ \fB\-\-version +Show program's version number and exit. +.TP +.B \-h\fR,\ \fB\-\-help +Show help message and exit. + +.SH SEE ALSO +.BR deluge (1), +.BR deluge-web (1), +.BR deluge-console (1) + +.SH AUTHORS +.B Deluge Team: http://www.deluge-torrent.org diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..3da1967 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx==7.2.* +myst-parser==2.0.* +sphinx_rtd_theme==2.0.* +sphinxcontrib-spelling==8.0.* +sphinx-autodoc-typehints==1.25.* 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 |