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. Configuration file for the Sphinx documentation builder.
This file does only contain a selection of the most common options. For a For a full list of options see the documentation:
full list see the documentation:
http://www.sphinx-doc.org/en/master/config 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 os
import sys 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'))
sys.path.insert(0, os.path.abspath('../src/pyelliptic'))
import version from importlib import import_module
import version # noqa:E402
# -- Project information ----------------------------------------------------- # -- Project information -----------------------------------------------------
project = u'PyBitmessage' 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' author = u'The Bitmessage Team'
# The short X.Y version # The short X.Y version
@ -50,12 +39,13 @@ release = version
# ones. # ones.
extensions = [ extensions = [
'sphinx.ext.autodoc', '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.intersphinx',
'sphinx.ext.linkcode',
'sphinx.ext.napoleon',
'sphinx.ext.todo', 'sphinx.ext.todo',
'sphinx.ext.coverage', 'sphinxcontrib.apidoc',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
'm2r', 'm2r',
] ]
@ -75,23 +65,29 @@ master_doc = 'index'
# #
# This is also used if you do content translation via gettext catalogs. # This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases. # 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 # List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files. # directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path . # 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. # The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx' 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 ------------------------------------------------- # -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for # The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes. # 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 # 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 # further. For a list of options available for each theme, see the
@ -114,10 +110,7 @@ html_static_path = ['_static']
# #
# html_sidebars = {} # html_sidebars = {}
# Deal with long lines in source view html_show_sourcelink = False
html_theme_options = {
'page_width': '1366px',
}
# -- Options for HTMLHelp output --------------------------------------------- # -- Options for HTMLHelp output ---------------------------------------------
@ -199,10 +192,75 @@ epub_exclude_files = ['search.html']
# -- Extension configuration ------------------------------------------------- # -- 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 --------------------------------------- # -- Options for intersphinx extension ---------------------------------------
# Example configuration for intersphinx: refer to the Python standard library. # 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 ---------------------------------------------- # -- 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 .. figure:: ../../../../_static/deps-sfdp.png
:alt: SFDP graph of dependencies :alt: SFDP graph of dependencies
:width: 100 pc :width: 100 pc
:index:`SFDP` graph of dependencies :index:`SFDP` graph of dependencies
.. figure:: ../../../../_static/deps-dot.png .. figure:: ../../../../_static/deps-dot.png

View File

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