Customize public qiskit apidoc documentation

Replace the full apidoc automatically generated documentation with a
set of pages that display only the public objects (using the class path
specified by the main import: ie "qiskit.QuantumProgram" instead of
"qistkit._quantumprogram.QuantumProgram") via custom templates using the
better-apidoc package.

Makefile

@@ -39,7 +39,10 @@ profile:
 	python3 -m unittest discover -p "profile*.py" -v
 
 doc:
-	export PYTHONPATH=$(PWD);sphinx-apidoc -f -o doc/_autodoc -d 5 -P -e qiskit;make -C doc html
+	export PYTHONPATH=$(PWD); \
+	better-apidoc -f -o doc/_autodoc_stubs -d 5 -e -t doc/_templates/better-apidoc qiskit qiskit/tools; \
+	sphinx-autogen doc/entry_autodoc_public.rst doc/_autodoc_stubs/*; \
+	make -C doc html
 
 clean:
 	make -C doc clean

doc/_templates/better-apidoc/module.rst

@@ -0,0 +1 @@
+TODO

doc/_templates/better-apidoc/package.rst

@@ -0,0 +1,45 @@
+{{ fullname }} package
+{% for item in range(8 + fullname|length) -%}={%- endfor %}
+
+.. automodule:: {{ fullname }}
+
+{% if submodules %}
+Submodules
+----------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../_autodoc_public
+{% for item in submodules %}
+    {{ item }}
+    {%- endfor %}
+{%- endif %}
+
+
+{% if subpackages %}
+Subpackages
+-----------
+
+.. autosummary::
+   :nosignatures:
+   :toctree: ../_autodoc_public
+{% for item in subpackages %}
+    {{ item }}
+    {%- endfor %}
+{%- endif %}
+
+
+{% if members_imports_refs %}
+Contents
+--------
+
+.. autosummary::
+    :nosignatures:
+{% for item in members_imports_refs -%}
+    {% set ref_type = item.split(':')[1] %}
+    {% if ref_type != 'mod' -%}
+    {% set ref_name = item.split(' ')[0].split('`')[1] -%}
+    {{ ref_name }}
+    {%- endif -%}
+    {%- endfor -%}
+{%- endif %}

doc/conf.py

@@ -33,6 +33,7 @@ from qiskit import __version__
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = ['sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',
     'sphinx.ext.doctest',
     'sphinx.ext.coverage',
@@ -41,6 +42,8 @@ extensions = ['sphinx.ext.autodoc',
     'sphinx.ext.githubpages',
     'sphinxcontrib.fulltoc']
 
+autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance', 'inherited-members']
+
 # Napoleon settings
 napoleon_google_docstring = True
 napoleon_numpy_docstring = False

doc/entry_autodoc_public.rst

@@ -0,0 +1,5 @@
+.. autosummary::
+   :nosignatures:
+   :toctree: _autodoc_public
+
+   qiskit.QuantumProgram

doc/index.rst

@@ -34,6 +34,15 @@ Main Modules
 * `Quantum Circuit <./_autodoc/qiskit._quantumcircuit.html>`__
 * :ref:`modindex`
 
+.. toctree::
+   :maxdepth: 4
+   :caption: Contents:
+             
+   SDK reference (public) <_autodoc_stubs/qiskit.html>
+
+.. include:: install.rst
+.. include:: entry_autodoc_public
+
 Authors (alphabetical)
 ======================