diff options
Diffstat (limited to '')
-rw-r--r-- | docs/source/contributing/code.md | 124 | ||||
-rw-r--r-- | docs/source/contributing/documentation.md | 14 | ||||
-rw-r--r-- | docs/source/contributing/index.md | 13 | ||||
-rw-r--r-- | docs/source/contributing/testing.md | 50 | ||||
-rw-r--r-- | docs/source/contributing/translations.md | 66 |
5 files changed, 267 insertions, 0 deletions
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 |