Adjusted conf and rst to fix modindex and get informative index

This commit is contained in:
Dmitri Bogomolov 2019-10-09 11:46:47 +03:00
parent c99997dbb9
commit 9a3a5ec9e8
Signed by untrusted user: g1itch
GPG Key ID: 720A756F18DEED13
4 changed files with 98 additions and 32 deletions

View File

@ -2,35 +2,24 @@
"""
Configuration file for the Sphinx documentation builder.
This file does only contain a selection of the most common options. For a
full list see the documentation:
For a full list of options see the documentation:
http://www.sphinx-doc.org/en/master/config
-- Path setup --------------------------------------------------------------
If extensions (or modules to document with autodoc) are in another directory,
add these directories to sys.path here. If the directory is relative to the
documentation root, use os.path.abspath to make it absolute, like shown here.
"""
import os
import sys
from sphinx.apidoc import main
from mock import Mock as MagicMock
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../src'))
sys.path.insert(0, os.path.abspath('../src/pyelliptic'))
import version
from importlib import import_module
import version # noqa:E402
# -- Project information -----------------------------------------------------
project = u'PyBitmessage'
copyright = u'2018, The Bitmessage Team' # pylint: disable=redefined-builtin
copyright = u'2019, The Bitmessage Team' # pylint: disable=redefined-builtin
author = u'The Bitmessage Team'
# The short X.Y version
@ -50,12 +39,13 @@ release = version
# ones.
extensions = [
'sphinx.ext.autodoc',
# 'sphinx.ext.doctest', # Currently disabled due to bad doctests
'sphinx.ext.coverage', # FIXME: unused
'sphinx.ext.imgmath', # legacy unused
'sphinx.ext.intersphinx',
'sphinx.ext.linkcode',
'sphinx.ext.napoleon',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
'sphinxcontrib.apidoc',
'm2r',
]
@ -75,23 +65,29 @@ master_doc = 'index'
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path .
exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
exclude_patterns = ['_build']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# Don't prepend every class or function name with full module path
add_module_names = False
# A list of ignored prefixes for module index sorting.
modindex_common_prefix = ['pybitmessage.']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
@ -114,10 +110,7 @@ html_static_path = ['_static']
#
# html_sidebars = {}
# Deal with long lines in source view
html_theme_options = {
'page_width': '1366px',
}
html_show_sourcelink = False
# -- Options for HTMLHelp output ---------------------------------------------
@ -199,10 +192,75 @@ epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
autodoc_mock_imports = [
'debug',
'pybitmessage.bitmessagekivy',
'pybitmessage.bitmessagemain',
'pybitmessage.bitmessageqt.addressvalidator',
'pybitmessage.helper_startup',
'pybitmessage.network.httpd',
'pybitmessage.network.https',
'ctypes',
'dialog',
'gi',
'kivy',
'logging',
'msgpack',
'numpy',
'pkg_resources',
'pycanberra',
'pyopencl',
'PyQt4',
'pyxdg',
'qrcode',
'stem',
]
# Apidoc settings
apidoc_module_dir = '../pybitmessage'
apidoc_output_dir = 'autodoc'
apidoc_excluded_paths = [
'bitmessagekivy', 'bitmessagemain.py', 'build_osx.py',
'bitmessageqt/addressvalidator.py', 'bitmessageqt/migrationwizard.py',
'bitmessageqt/newaddresswizard.py',
'class_objectProcessor.py', 'defaults.py', 'helper_startup.py',
'kivymd', 'main.py', 'navigationdrawer', 'network/http*',
'pybitmessage', 'queues.py', 'tests', 'version.py'
]
apidoc_module_first = True
apidoc_separate_modules = True
apidoc_toc_file = False
apidoc_extra_args = ['-a']
# Napoleon settings
napoleon_google_docstring = True
# linkcode function
def linkcode_resolve(domain, info):
"""This generates source URL's for sphinx.ext.linkcode"""
if domain != 'py' or not info['module']:
return
try:
home = os.path.abspath(import_module('pybitmessage').__path__[0])
mod = import_module(info['module']).__file__
except ImportError:
return
repo = 'https://github.com/Bitmessage/PyBitmessage/blob/v0.6/src%s'
path = mod.replace(home, '')
if path != mod:
# put the link only for top level definitions
if len(info['fullname'].split('.')) > 1:
return
if path.endswith('.pyc'):
path = path[:-1]
return repo % path
# -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}
intersphinx_mapping = {'https://docs.python.org/2.7/': None}
# -- Options for todo extension ----------------------------------------------

View File

@ -1,2 +1,2 @@
.. mdinclude:: fabfile/README.md
.. mdinclude:: ../../../fabfile/README.md

View File

@ -62,7 +62,7 @@ To re-build them, run `fab build_docs:dep_graphs=true`. Note that the dot graph
.. figure:: ../../../../_static/deps-sfdp.png
:alt: SFDP graph of dependencies
:width: 100 pc
:index:`SFDP` graph of dependencies
.. figure:: ../../../../_static/deps-dot.png

View File

@ -1,12 +1,20 @@
.. mdinclude:: ../README.md
Documentation
-------------
.. toctree::
:maxdepth: 3
autodoc/pybitmessage
Legacy pages
------------
.. toctree::
:maxdepth: 2
overview
usage
contribute
Indices and tables
------------------