diff --git a/Makefile b/Makefile index 9392de9979..8f8b1f8086 100644 --- a/Makefile +++ b/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 diff --git a/doc/_templates/better-apidoc/module.rst b/doc/_templates/better-apidoc/module.rst new file mode 100644 index 0000000000..30404ce4c5 --- /dev/null +++ b/doc/_templates/better-apidoc/module.rst @@ -0,0 +1 @@ +TODO \ No newline at end of file diff --git a/doc/_templates/better-apidoc/package.rst b/doc/_templates/better-apidoc/package.rst new file mode 100644 index 0000000000..64031f2925 --- /dev/null +++ b/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 %} diff --git a/doc/conf.py b/doc/conf.py index 4bb1936574..fdd329a9c3 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/entry_autodoc_public.rst b/doc/entry_autodoc_public.rst new file mode 100644 index 0000000000..4d20dd2f1b --- /dev/null +++ b/doc/entry_autodoc_public.rst @@ -0,0 +1,5 @@ +.. autosummary:: + :nosignatures: + :toctree: _autodoc_public + + qiskit.QuantumProgram diff --git a/doc/index.rst b/doc/index.rst index e1d8378e26..b9e6b82ba5 100644 --- a/doc/index.rst +++ b/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) ======================