From 9a3a5ec9e8886ae3163ded9059526c69b544acd2 Mon Sep 17 00:00:00 2001 From: Dmitri Bogomolov <4glitch@gmail.com> Date: Wed, 9 Oct 2019 11:46:47 +0300 Subject: [PATCH] Adjusted conf and rst to fix modindex and get informative index --- docs/conf.py | 114 ++++++++++++++----- docs/contribute.dir/develop.dir/fabric.rst | 2 +- docs/contribute.dir/develop.dir/overview.rst | 2 +- docs/index.rst | 12 +- 4 files changed, 98 insertions(+), 32 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a4dae7c7..96c9f146 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -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 ---------------------------------------------- diff --git a/docs/contribute.dir/develop.dir/fabric.rst b/docs/contribute.dir/develop.dir/fabric.rst index 434ccf7b..8003f33a 100644 --- a/docs/contribute.dir/develop.dir/fabric.rst +++ b/docs/contribute.dir/develop.dir/fabric.rst @@ -1,2 +1,2 @@ -.. mdinclude:: fabfile/README.md +.. mdinclude:: ../../../fabfile/README.md diff --git a/docs/contribute.dir/develop.dir/overview.rst b/docs/contribute.dir/develop.dir/overview.rst index e83d884b..342c9dbb 100644 --- a/docs/contribute.dir/develop.dir/overview.rst +++ b/docs/contribute.dir/develop.dir/overview.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index 9dddfa28..cc8c9523 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,12 +1,20 @@ .. mdinclude:: ../README.md +Documentation +------------- +.. toctree:: + :maxdepth: 3 + + autodoc/pybitmessage + +Legacy pages +------------ .. toctree:: :maxdepth: 2 - overview usage contribute - + Indices and tables ------------------