diff options
author | Calum Lind <calumlind+deluge@gmail.com> | 2019-05-21 02:19:57 +0100 |
---|---|---|
committer | Calum Lind <calumlind+deluge@gmail.com> | 2019-05-21 15:23:45 +0100 |
commit | 65f6ede8b24ad093285a514360a1082cec892f49 (patch) | |
tree | 6f778626ae41890cd3dc9e7a1483f5e3e765e21d | |
parent | 515dbcc5d9de572f46ebacb2baa47ae762b06036 (diff) | |
download | deluge-65f6ede8b24ad093285a514360a1082cec892f49.tar.gz deluge-65f6ede8b24ad093285a514360a1082cec892f49.tar.bz2 deluge-65f6ede8b24ad093285a514360a1082cec892f49.zip |
[Docs] Updates and fixes to build on Python 3
- 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.
-rw-r--r-- | .readthedocs.yml | 20 | ||||
-rw-r--r-- | .travis.yml | 1 | ||||
-rw-r--r-- | deluge/transfer.py | 2 | ||||
-rw-r--r-- | docs/requirements.txt (renamed from requirements-docs.txt) | 2 | ||||
-rw-r--r-- | docs/source/conf.py | 187 | ||||
-rw-r--r-- | docs/source/contributing/documentation.md | 2 | ||||
-rw-r--r-- | requirements-dev.txt | 2 | ||||
-rw-r--r-- | tox.ini | 3 |
8 files changed, 120 insertions, 99 deletions
diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 000000000..1b43c5ed2 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,20 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +formats: all + +# Optionally set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: requirements.txt + - requirements: docs/requirements.txt diff --git a/.travis.yml b/.travis.yml index 0b5f11450..f3adfa1e2 100644 --- a/.travis.yml +++ b/.travis.yml @@ -25,7 +25,6 @@ matrix: env: TOX_ENV=lint - name: Docs build env: TOX_ENV=docs - python: 2.7 - name: GTK unit tests env: TOX_ENV=gtkui - name: Plugins unit tests diff --git a/deluge/transfer.py b/deluge/transfer.py index 10f6d51e0..6b26549e2 100644 --- a/deluge/transfer.py +++ b/deluge/transfer.py @@ -31,7 +31,7 @@ class DelugeTransferProtocol(Protocol, object): Data messages are transfered with a header containing a protocol version and the length of the data to be transfered (payload). - The format is: + The format is:: ubyte uint4 bytestring |.version.|..size..|.....body.....| diff --git a/requirements-docs.txt b/docs/requirements.txt index e23c1e1e3..ea2d9e329 100644 --- a/requirements-docs.txt +++ b/docs/requirements.txt @@ -1,3 +1,3 @@ -sphinx==1.7.* +sphinx==2.0.* recommonmark==0.4.* sphinx_rtd_theme diff --git a/docs/source/conf.py b/docs/source/conf.py index ccc3b33e3..313c35289 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -10,7 +10,6 @@ # All configuration values have a default value; values that are commented out # serve to show the default value. -import __builtin__ import os import sys from datetime import date @@ -18,33 +17,12 @@ from datetime import date import pkg_resources from recommonmark.states import DummyStateMachine from recommonmark.transform import AutoStructify +from six.moves import builtins from sphinx.ext import apidoc from sphinx.ext.autodoc import ClassDocumenter, bool_option -try: - from ...version import get_version -except ImportError: - get_version = None - -# Monkey patch to fix recommonmark 0.4 doc reference issues. -orig_run_role = DummyStateMachine.run_role - - -def run_role(self, name, options=None, content=None): - if name == 'doc': - name = 'any' - return orig_run_role(self, name, options, content) - - -DummyStateMachine.run_role = run_role - -# Must add these for autodoc to import packages successully -__builtin__.__dict__['_'] = lambda x: x -__builtin__.__dict__['_n'] = lambda s, p, n: s if n == 1 else p - -# 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. +# 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( @@ -52,69 +30,19 @@ sys.path.append( ) ) ) +# Importing version only possible after add project root to sys.path. +try: + from version import get_version +except ImportError: + get_version = None -class Mock(object): - - __all__ = [] - - def __init__(self, *args, **kwargs): - pass - - def __call__(self, *args, **kwargs): - return Mock() - - @classmethod - def __getattr__(cls, name): - if name in ('__file__', '__path__'): - return '/dev/null' - elif name[0] == name[0].upper(): - mock_type = type(name, (), {}) - mock_type.__module__ = __name__ - return mock_type - else: - return Mock() - - def __add__(self, other): - return other - - def __or__(self, __): - return Mock() - - -# Use custom mock as autodoc_mock_imports fails to handle these modules. -MOCK_MODULES = ['deluge._libtorrent', 'xdg', 'xdg.BaseDirectory'] - -for mod_name in MOCK_MODULES: - sys.modules[mod_name] = Mock() - -autodoc_mock_imports = [ - 'twisted', - 'rencode', - 'OpenSSL', - 'PIL', - 'libtorrent', - 'psyco', - 'gi', - 'cairo', - 'curses', - 'win32api', - 'win32file', - 'win32process', - 'win32pipe', - 'pywintypes', - 'win32con', - 'win32event', - 'pytest', - 'mock', - 'mako', - 'zope', - 'zope.interface', -] - # 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 = [ @@ -142,17 +70,13 @@ project = 'Deluge' current_year = date.today().year copyright = '2008-%s, Deluge Team' % current_year # noqa: A001 -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. -# - -# The short X.Y version. +# The full version, including alpha/beta/rc tags. if get_version: - version = get_version(prefix='deluge-', suffix='.dev0') + release = get_version(prefix='deluge-', suffix='.dev0') else: - version = pkg_resources.get_distribution('Deluge').version -# The full version, including alpha/beta/rc tags. -release = version + release = pkg_resources.get_distribution('Deluge').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: @@ -286,6 +210,72 @@ latex_documents = [ # If false, no module index is generated. # latex_use_modindex = True + +# Autodoc section +# --------------- +class Mock(object): + + __all__ = [] + + def __init__(self, *args, **kwargs): + pass + + def __call__(self, *args, **kwargs): + return '' + + @classmethod + def __getattr__(cls, name): + if name in ('__file__', '__path__', 'xdg_config_home'): + return '/dev/null' + elif name[0] == name[0].upper(): + mock_type = type(name, (), {}) + mock_type.__module__ = __name__ + return mock_type + else: + return Mock() + + def __add__(self, other): + return other + + def __or__(self, __): + return Mock() + + +# Use custom mock as autodoc_mock_imports fails to handle these modules. +MOCK_MODULES = ['deluge._libtorrent', 'xdg', 'xdg.BaseDirectory'] + +for mod_name in MOCK_MODULES: + sys.modules[mod_name] = Mock() + +# Must add these for autodoc to import packages successully +builtins.__dict__['_'] = lambda x: x +builtins.__dict__['_n'] = lambda s, p, n: s if n == 1 else p + +autodoc_mock_imports = [ + '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 @@ -297,6 +287,19 @@ def maybe_skip_member(app, what, name, obj, skip, options): return True +# Monkey patch to fix recommonmark 0.4 doc reference issues. +orig_run_role = DummyStateMachine.run_role + + +def run_role(self, name, options=None, content=None): + if name == 'doc': + name = 'any' + return orig_run_role(self, name, options, content) + + +DummyStateMachine.run_role = run_role + + # Run the sphinx-apidoc to create package/modules rst files for autodoc. def run_apidoc(__): cur_dir = os.path.abspath(os.path.dirname(__file__)) diff --git a/docs/source/contributing/documentation.md b/docs/source/contributing/documentation.md index a994c5aa4..cd72b85dd 100644 --- a/docs/source/contributing/documentation.md +++ b/docs/source/contributing/documentation.md @@ -4,7 +4,7 @@ We use Sphinx to create the documentation from source files and docstrings in code. - pip install -r requirements-docs.txt + pip install -r docs/requirements.txt python setup.py build_docs The resulting html files are in `docs/build/html`. diff --git a/requirements-dev.txt b/requirements-dev.txt index 0b08e7b5f..34f57cfa8 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,5 +1,5 @@ -r requirements.txt --r requirements-docs.txt +-r docs/requirements.txt -r requirements-tests.txt sphinx-autobuild tox @@ -42,7 +42,7 @@ deps = [basedocs] deps = {[basesetup]deps} - -rrequirements-docs.txt + -rdocs/requirements.txt # ====================== # Test environment setup @@ -147,7 +147,6 @@ commands = # =================== [testenv:docs] -basepython = python2.7 # Exclude site-packages so local builds have a similar environment to ReadTheDocs. sitepackages = False skip_install = True |