mirror of
https://git.deluge-torrent.org/deluge
synced 2025-08-11 02:48:39 +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:
parent
9dcd90056d
commit
82ecf8a416
31 changed files with 728 additions and 101 deletions
115
docs/source/contributing/code.md
Normal file
115
docs/source/contributing/code.md
Normal file
|
@ -0,0 +1,115 @@
|
|||
# Contributing code
|
||||
|
||||
## Basic requirements and standards
|
||||
|
||||
- A [new ticket](http://dev.deluge-torrent.org/newticket) is required for bugs
|
||||
or features. Search the ticket system first, to avoid filing a duplicate.
|
||||
- Ensure code follows the [syntax and conventions](#syntax-and-conventions).
|
||||
- Code must pass tests. See [testing.md] for
|
||||
information on how to run and write unit tests.
|
||||
- Commit messages are informative.
|
||||
|
||||
## Pull request process:
|
||||
|
||||
- Fork us on [github](https://github.com/deluge-torrent/deluge).
|
||||
- Clone your repository.
|
||||
- Create a feature branch for your issue.
|
||||
- Apply your changes:
|
||||
- Add them, and then commit them to your branch.
|
||||
- Run the tests until they pass.
|
||||
- When you feel you are finished, rebase your commits to ensure a simple
|
||||
and informative commit log.
|
||||
- Create a pull request on github from your forked repository.
|
||||
- Verify that the tests run by [Travis-ci](https://travis-ci.org/deluge-torrent/deluge)
|
||||
are passing.
|
||||
|
||||
## Syntax and conventions
|
||||
|
||||
### Code formatters
|
||||
|
||||
We use two applications to automatically format the code to save development
|
||||
time. They are both run with pre-commit.
|
||||
|
||||
#### Black
|
||||
|
||||
- Python
|
||||
|
||||
#### Prettier
|
||||
|
||||
- Javascript
|
||||
- CSS
|
||||
- YAML
|
||||
- Markdown
|
||||
|
||||
### Common
|
||||
|
||||
- Line length: `79` chars.
|
||||
- Indent: `4 spaces`, no tabs.
|
||||
- All code should use `'single quotes'`.
|
||||
|
||||
### Python
|
||||
|
||||
We follow [PEP8](http://www.python.org/dev/peps/pep-0008/) and
|
||||
[Python Code Style](http://docs.python-guide.org/en/latest/writing/style/)
|
||||
which is adhered to with Black formatter.
|
||||
|
||||
- Code '''must''' pass [flake8](https://pypi.python.org/pypi/flake8) (w/[https://pypi.python.org/pypi/flake8-quotes flake8-quotes]), [https://pypi.python.org/pypi/isort isort] and [http://www.pylint.org/ Pylint] source code checkers.
|
||||
|
||||
flake8 deluge
|
||||
isort -rc -df deluge
|
||||
pylint deluge
|
||||
pylint deluge/plugins/\*/deluge/
|
||||
|
||||
- Using the [http://pre-commit.com/ pre-commit] app can aid in picking up
|
||||
issues before creating git commits.
|
||||
|
||||
#### Strings and bytes
|
||||
|
||||
To prevent bugs or errors in the code byte strings (`str`) must be decoded to
|
||||
strings (unicode strings, `unicode`) on input and then encoded on output.
|
||||
|
||||
_Notes:_
|
||||
|
||||
- PyGTK/GTK+ will accept `str` (utf8 encoded) or `unicode` but will only return
|
||||
`str`. See [http://python-gtk-3-tutorial.readthedocs.org/en/latest/unicode.html GTK+ Unicode] docs.
|
||||
- There is a `bytearray` type which enables in-place modification of a string.
|
||||
See [Python Bytearrays](http://stackoverflow.com/a/9099337/175584)
|
||||
- Python 3 renames `unicode` to `str` type and byte strings become `bytes` type.
|
||||
|
||||
### Javascript
|
||||
|
||||
- Classes should follow the Ext coding style.
|
||||
- Class names should be in !CamelCase
|
||||
- Instances of classes should use camelCase.
|
||||
|
||||
### Path separators
|
||||
|
||||
- All relative path separators used within code should be converted to posix
|
||||
format `/`, so should not contain `\` or `\\`. This is to prevent confusion
|
||||
when dealing with cross-platform clients and servers.
|
||||
|
||||
### Docstrings
|
||||
|
||||
All new docstrings must use Napoleon
|
||||
[Google Style](http://www.sphinx-doc.org/en/stable/ext/napoleon.html)
|
||||
with old docstrings eventually converted over.
|
||||
|
||||
Google Style example:
|
||||
|
||||
def func(arg):
|
||||
"""Function purpose.
|
||||
|
||||
Args:
|
||||
arg (type): Description.
|
||||
|
||||
Returns:
|
||||
type: Description. If the line is too, long indent next
|
||||
line with three spaces.
|
||||
"""
|
||||
return
|
||||
|
||||
See complete list of [http://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#docstring-sections supported headers].
|
||||
|
||||
Verify that the documentation parses correctly with:
|
||||
|
||||
python setup.py build_docs
|
Loading…
Add table
Add a link
Reference in a new issue