Adjusted conf and rst to fix modindex and get informative index

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 ----------------------------------------------
 

docs/contribute.dir/develop.dir/fabric.rst

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

docs/index.rst

@@ -1,9 +1,17 @@
 .. mdinclude:: ../README.md
 
+Documentation
+-------------
+.. toctree::
+   :maxdepth: 3
+
+   autodoc/pybitmessage
+
+Legacy pages
+------------
 .. toctree::
    :maxdepth: 2
 
-   overview
    usage
    contribute