Fix rendering issues in ReadTheDocs by specifying latest version of
sphinx-rtd-theme. Normally not an issue to install this latest
dependency from doc/requirement.txt but RTD installs in the env an older
version (<0.5) before running requirements file install
thus sphinx-rtd-theme is not upgraded unless a version is specified.
See-also: https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
If a libtorrent return type was specified e.g.
def get_lt_status(self) -> 'lt.torrent_status'
Even as a string autodoc_typehints module would raise and error:
Handler <function process_docstring at 0x7f6c16c8ec10> for event 'autodoc-process-docstring' threw an exception (exception: getattr(): attribute name must be string)
This was a result of using a custom mock in Sphinx autodoc config and
this Mock object name or qualname returns an object instead of str.
Testing with putting modules in autodoc_mock_imports again showed no
issues so removing custom mock
Ref: https://github.com/tox-dev/sphinx-autodoc-typehints/issues/220
Standardize docstrings in core.py to google standard.
Remove type hints in docstrings in favor of the ones in method signatures.
Use function signature type hints in autodoc generated docs.
Change Deferred type hints to strings.
Older versions of twisted (<21.7) don't
support generic Deferred type hinting,
this prevents crashes on those versions.
Closes: https://github.com/deluge-torrent/deluge/pull/359
Typing is broken with older versions of Twisted e.g. with v21.2
deluge/deluge/core/core.py", line 404, in Core
) -> defer.Deferred[str]:
TypeError: 'type' object is not subscriptable
Also it might not be compatible with Python 3.6 or 3.7 with use of
certain types such as dict rather than Dict
This reverts commit 4096cdfdfe.
Ref: https://twistedmatrix.com/trac/ticket/9816
Standardize docstrings in core.py to google standard.
Remove type hints in docstrings in favor of the ones in method signatures.
Use function signature type hints in autodoc generated docs.
Closes: https://github.com/deluge-torrent/deluge/pull/359
CI docs build was failing with the following error when using latest
sphinx-contrib-spelling 7.3.1
error: option -j not recognized
Fixed by pinning to previous version.
GitHub-ref: https://github.com/sphinx-contrib/spelling/issues/142
* Removed all __future__ imports from code
* Removed all six dependencies
* Removed all future_builtins imports
* Removed all Python 2 related code
Closes: deluge-torrent/deluge#325
We used recommonmark so that we can use markdown in sphinx but it is
buggy and now so switch to better supported MyST-parser.
* Fixed incorrect heading warnings in markdown.
* Added sphinx toctree to markdown using directive as required by MyST.
* Upgraded Sphinx to 4.3
Ref: https://myst-parser.readthedocs.io
* Added required dependency setuptools to install_requires
* Remove optional dependency ipaddress from install_requires
* Created extras_require in setup.py. The optional dependencies should
not be included in install_requires so that users can either install
forked dependencies or remove problematic ones. Updated documentation to
detail how to install these optional dependencies.
* Fixed README badge
Refs:
* https://dev.deluge-torrent.org/ticket/3470
* https://dev.deluge-torrent.org/ticket/3282
* https://dev.deluge-torrent.org/ticket/3353
* Error occurring with Pytest 5.4 so pin to below that version.
* Fix minor issues with Travis config.
* Use full command-switches for pytest in tox config.
* Remove pin for pip as issue with pip-wheel-metadata was fixed in 19.3
* Remove tox-venv as causing issues of incompatible packages installed.
The latest versions of the virtualenv package should handle these
duties.
- Use sphinxcontrib.spelling with custom wordlist.
- Skip the checking of the modules documents as they raise
false-positives.
- Add a setup.py spellcheck_docs command.
- Fix spelling and other issues.
- Add a doc favicon.
Use post segment instead of dev for non-dev tags.
Default to 'deluge-' and '.dev0' to simplify getting version.
Refactor to use subprocess.check_output
Use deluge.common.get_version as fallback in docs conf.
- Updates to the sphinx conf
- Applied Mock fixes to build on Python 3.
- Group patches at bottom of conf file.
- Use just a major.minor for version.
- Specify Sphinx 2.0 version requirement.
- Move requirements.txt to docs dir.
- Add readthedocs config
- Fix docstring code block rst formatting issue.
There were issues with dependencies and tox environments under Python 3
so refactored the tox configuration to be more consistent and clearer.
- Moved travis to default to Python 3 for linting and tests.
- Fixed missing mock for cairo in sphinx config.
- Collated the base deps sections to improve readability.
- Added PYTEST_ADDOPTS env to override pytest verbosity in just tox
tests as this was a common option being used.
- Renamed env 'testcoverage' to the more concise 'coverage' and moved
html creation under single env as handy to have this output as well
as report.
- Cleaned up the isort config for gtk3.
- Added `bad-continuation` to pylint config as conflcts with black
formatting.
- Fix isort issue with bbfreeze script. This will likely be removed
in future so just skip sorting it.
With move to GTK3 needed to update the mocking of external modules.
There is a new autodoc option `autodoc_mock_imports` so use this instead
of the custom mock class.
There are some build warnings output using autodoc mock:
TypeError: unsupported operand type(s) for |: '_MockObject' and '_MockObject'
Will resolve these later as the build passes.
The apidoc modules were not being generated on ReadTheDocs because
there is no way to run sphinx-apidoc manually.
Moved the running of sphinx-apidoc into conf.py.
Added zope.interface minimum version to fix Readthedocs warning.
The use of pkg_resource.require caused an unwanted requirements lookup
that errored out the sphinx build when no dependencies are installed.
This is fixed by switching to pkg_resources.get_distribution.
Also changed the tox docs env to not install Deluge as the setup.py
now contains install_requires which is unwanted.
- 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.
