[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.
This commit is contained in:
Calum Lind 2018-10-04 11:55:53 +01:00
commit 36606fc448
6 changed files with 40 additions and 24 deletions

View file

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

View file

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

3
requirements-docs.txt Normal file
View file

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

View file

@ -22,7 +22,9 @@ known_third_party =
# Ignore Windows specific modules. # Ignore Windows specific modules.
bbfreeze, win32verstamp, bbfreeze, win32verstamp,
# Ignore gtk modules, primarily for tox testing. # 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 known_first_party = msgfmt, deluge
order_by_type = true order_by_type = true
not_skip = __init__.py not_skip = __init__.py

View file

@ -535,7 +535,7 @@ _package_data['deluge.ui.gtkui'] = ['glade/*.ui']
if 'dev' not in _version: if 'dev' not in _version:
_exclude_package_data['deluge.ui.web'] = ['*-debug.js', '*-debug.css'] _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 = [ tests_require = [
'coverage', 'coverage',
'flake8', 'flake8',

View file

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