[Docs] Add markdown support

- Use recommonmark to enable use of markdown files in docs.
- Fix theme not specified
- Remove unused spelling module.
- Cleanup mocking modules in conf so building docs requires only Sphinx.
- Simplify tox section, including use of requirements-docs file. Added
  slimit dependency for sdist-ing deluge package.

docs/rtd_requirements.txt

@@ -1,6 +0,0 @@
-twisted
-pyopenssl
-pyxdg
-service_identity
-pillow
-mako

docs/source/conf.py

@@ -16,6 +16,7 @@ import sys
 from datetime import date
 
 import pkg_resources
+from recommonmark.transform import AutoStructify
 
 try:
     from ...version import get_version
@@ -59,19 +60,28 @@ class Mock(object):
         else:
             return Mock()
 
+    def __add__(self, other):
+        return other
+
     def __or__(self, __):
         return Mock()
 
 
-MOCK_MODULES = [
-    'deluge.ui.gtkui.gtkui',
-    'deluge._libtorrent',
+# 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',
+    'OpenSSL',
+    'PIL',
     'libtorrent',
     'psyco',
     'pygtk',
     'gtk',
     'gobject',
-    'gtk.gdk',
     'pango',
     'cairo',
     'pangocairo',
@@ -83,11 +93,13 @@ MOCK_MODULES = [
     'pywintypes',
     'win32con',
     'win32event',
+    'pytest',
+    'mock',
+    'mako',
+    'zope',
+    'zope.interface',
 ]
 
-for mod_name in MOCK_MODULES:
-    sys.modules[mod_name] = Mock()
-
 # General configuration
 # ---------------------
 
@@ -104,7 +116,8 @@ extensions = [
 templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
+source_suffix = ['.rst', '.md']
 
 # The master toctree document.
 master_doc = 'index'
@@ -160,11 +173,11 @@ pygments_style = 'sphinx'
 
 # Options for HTML output
 # -----------------------
-
+html_theme = 'sphinx_rtd_theme'
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
-html_style = 'default.css'
+# html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -257,3 +270,10 @@ latex_documents = [
 
 # If false, no module index is generated.
 # latex_use_modindex = True
+
+
+def setup(app):
+    app.add_config_value(
+        'recommonmark_config', {'auto_toc_tree_section': 'Contents'}, True
+    )
+    app.add_transform(AutoStructify)

requirements-docs.txt

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

setup.cfg

@@ -22,7 +22,9 @@ known_third_party =
 # Ignore Windows specific modules.
     bbfreeze, win32verstamp,
 # Ignore gtk modules, primarily for tox testing.
-    pygtk, gtk, gobject, gtk.gdk, pango, cairo, pangocairo
+    pygtk, gtk, gobject, gtk.gdk, pango, cairo, pangocairo,
+# Ignore sphinx dependencies.
+    recommonmark,
 known_first_party = msgfmt, deluge
 order_by_type = true
 not_skip = __init__.py

setup.py

@@ -535,7 +535,7 @@ _package_data['deluge.ui.gtkui'] = ['glade/*.ui']
 if 'dev' not in _version:
     _exclude_package_data['deluge.ui.web'] = ['*-debug.js', '*-debug.css']
 
-docs_require = ['Sphinx', 'recommonmark', 'sphinx-rtd-theme', 'sphinxcontrib-spelling']
+docs_require = ['sphinx', 'recommonmark', 'sphinx-rtd-theme']
 tests_require = [
     'coverage',
     'flake8',

tox.ini

@@ -164,10 +164,8 @@ commands =
 sitepackages = False
 changedir = docs
 deps =
-    {[testenv]deps}
-    sphinx==1.7.*
-whitelist_externals =
-    {[testenv]whitelist_externals}
+    slimit
+    -rrequirements-docs.txt
 
 [testenv:docs]
 sitepackages = {[docsbase]sitepackages}
@@ -182,10 +180,9 @@ sitepackages = {[docsbase]sitepackages}
 changedir = {[docsbase]changedir}
 deps =
     {[docsbase]deps}
-    coverage
     pytest-cov
 whitelist_externals =
-    {[docsbase]whitelist_externals}
+    pytest
     mkdir
 commands =
     mkdir -p build/doccoverage