[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.

.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

.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

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.....|

docs/requirements.txt

@@ -1,3 +1,3 @@
-sphinx==1.7.*
+sphinx==2.0.*
 recommonmark==0.4.*
 sphinx_rtd_theme

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.
-if get_version:
-    version = get_version(prefix='deluge-', suffix='.dev0')
-else:
-    version = pkg_resources.get_distribution('Deluge').version
 # The full version, including alpha/beta/rc tags.
-release = version
+if get_version:
+    release = get_version(prefix='deluge-', suffix='.dev0')
+else:
+    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__))

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`.

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

tox.ini

@@ -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