Sphinx documentation for the Python API (#40)

* Add reST stubs for Jet Python package

* Add generated Python API docs to 'clean' target

* Update conf.py to generate Python API docs

* Include autosummary templates based on SF and PL

* Fix Doxygen comment formatting in Tensor.hpp

* Add module docstring to jet package

* Move constructor docstrings to class docstrings

* Update changelog

* Update PR number in changelog

* Update name of TBCC to TBC after merge

* Remove trivial inheritance diagram from circuit.py

* Fix 'Key Concepts' and 'Getting Started' quick links

* Replace tensors.html link with introduction.html

* Add API documentation for Python bindings

* Update TensorNetworkIO docstrings to match Python package conventions

* Update TensorNetwork docstrings to match Python package conventions

* Update Tensor docstrings to match Python package conventions

* Update TBC docstrings to match Python package conventions

* Update PathInfo docstrings to match Python package conventions

* Apply C++ formatter

* Remove redundant import

* Add examples to interpreter.py docstrings

* Build Python wheel in documentation workflow

* Apply suggestions from code review

Co-authored-by: Josh Izaac <[email protected]>

* Remove MagicMock() modules

* Restore tildes to remove class ambiguity

* Update 'docs' target to install Python package

* Install wheel prior to installing quantum-jet wheel

* Defer *.whl wildcard expansion by creating 'dist' target

* Fix typo in 'dist' target

* Fix accidental blockquote caused by docstring indentation

* Distinguish overloaded functions and methods

* Restore use of josh146/sphinx-action GitHub Action

* Apply suggested Sphinx build options

* Move Sphinx options to 'docs' target of Makefile

* Use Haskell syntax highlighting in XIR blocks

* Replace 'cd' with Makefile '-C' flag

* Try quotes around build command

* Restore GitHub Actions workflow

* Replace '.Class' with 'jet.Class'

Co-authored-by: Josh Izaac <[email protected]>

.github/CHANGELOG.md

@@ -74,6 +74,8 @@
 
 ### Documentation
 
+* The Sphinx documentation now includes API documentation for the `jet` Python package. [(#40)](https://github.com/XanaduAI/jet/pull/40)
+
 * The "Using Jet" section of the Sphinx documentation website now compiles with the latest Jet headers. [(#26)](https://github.com/XanaduAI/jet/pull/26)
 
 * The license comment headers at the top of the IR source files have been removed. [(#14)](https://github.com/XanaduAI/jet/pull/14)

.github/workflows/documentation.yml

@@ -22,11 +22,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v2
 
-      - uses: josh146/sphinx-action@master
-        with:
-          docs-folder: "docs/"
-          pre-build-command: "apt install -y doxygen && pip3 install -r requirements.txt"
-          build-command: "make html"
+      - name: Install dependencies
+        run: sudo apt install -y libopenblas-dev python3.8-dev doxygen graphviz
+
+      - name: Build documentation
+        run: make docs
 
       - name: Upload HTML
         uses: actions/upload-artifact@v2

.gitignore

@@ -51,4 +51,5 @@ docs/__pycache__/*
 docs/_build/*
 docs/_ext/__pycache__/*
 docs/api/*
+docs/code/api/*
 docs/doxyoutput/*

Makefile

@@ -13,7 +13,9 @@ TARGETS
 
   uninstall [prefix=<path>]   Remove Jet headers from <path>/include, defaults to $(.DEFAULT_PREFIX)
 
-  test                        Build and run C++ tests (requires Cmake)
+  test                        Build and run C++ tests (requires CMake)
+
+  dist                        Build the Python source and wheel distributions
 
   docs                        Build docs (requires Doxygen, Pandoc and pip)
 
@@ -54,20 +56,26 @@ test: $(.TEST_BUILD_DIR)
 	$(.TEST_BUILD_DIR)/test/runner
 
 
+.PHONY: dist
+dist:
+	cd python && $(MAKE) dist
+
+
 .PHONY: docs
-docs: $(.VENV_DIR)
-	. $(.VENV_DIR)/bin/activate; cd ./docs && $(MAKE) html
+docs: $(.VENV_DIR) dist
+	$(.VENV_DIR)/bin/pip install -q $(wildcard dist/*.whl) --upgrade
+	. $(.VENV_DIR)/bin/activate; cd docs && $(MAKE) html SPHINXOPTS="-W --keep-going"
 
 
 .PHONY: clean
 clean:
-	rm -rf ./docs/_build ./docs/api ./docs/doxyoutput
-	rm -rf $(.TEST_BUILD_DIR)
-	rm -rf $(.VENV_DIR)
+	rm -rf ./docs/_build ./docs/api ./docs/code/api ./docs/doxyoutput
+	rm -rf $(.TEST_BUILD_DIR) $(.VENV_DIR) ./dist
 
 
 $(.VENV_DIR):
 	python3 -m venv $@
+	$@/bin/pip install -q wheel
 	$@/bin/pip install -q -r docs/requirements.txt
 
 

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,86 @@
+{{ fullname }}
+{{ underline }}
+
+.. autoclass:: {{ fullname }}
+   :show-inheritance:
+
+   {% if '__init__' in methods %}
+     {% set caught_result = methods.remove('__init__') %}
+   {% endif %}
+
+   {% block attributes_documentation %}
+   {% if attributes %}
+
+   .. raw:: html
+
+      <a class="attr-details-header collapse-header" data-toggle="collapse" href="#attrDetails" aria-expanded="false" aria-controls="attrDetails">
+         <h2 style="font-size: 24px;">
+            <i class="fas fa-angle-down rotate" style="float: right;"></i> Attributes
+         </h2>
+      </a>
+      <div class="collapse" id="attrDetails">
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+   {%- endfor %}
+
+   .. raw:: html
+
+      </div>
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_documentation %}
+   {% if methods %}
+
+   .. raw:: html
+
+      <a class="meth-details-header collapse-header" data-toggle="collapse" href="#methDetails" aria-expanded="false" aria-controls="methDetails">
+         <h2 style="font-size: 24px;">
+            <i class="fas fa-angle-down rotate" style="float: right;"></i> Methods
+         </h2>
+      </a>
+      <div class="collapse" id="methDetails">
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% for item in methods %}
+   .. automethod:: {{ item }}
+   {%- endfor %}
+
+   .. raw:: html
+
+      </div>
+
+   {% endif %}
+   {% endblock %}
+
+   .. raw:: html
+
+      <script type="text/javascript">
+         $(".collapse-header").click(function () {
+             $(this).children('h2').eq(0).children('i').eq(0).toggleClass("up");
+         })
+      </script>

docs/_templates/autosummary/module.rst

@@ -0,0 +1,40 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+      :toctree:
+
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+      :toctree:
+
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/_templates/autosummary_core/base.rst

@@ -0,0 +1,17 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{% if module.split(".")[1:] | length >= 1 %}
+	{% set mod = module.split(".")[1:] | join(".") %}
+	{% set mod = "jet." + mod %}
+{% else %}
+	{% set mod = "jet" %}
+{% endif %}
+
+{{ mod }}.{{ objname }}
+={% for i in range(mod|length) %}={% endfor %}{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

docs/_templates/autosummary_core/class.rst

@@ -0,0 +1,99 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{% if module.split(".")[1:] | length >= 1 %}
+	{% set mod = module.split(".")[1:] | join(".") %}
+	{% set mod = "jet." + mod %}
+{% else %}
+	{% set mod = "jet" %}
+{% endif %}
+
+{{ mod }}.{{ objname }}
+={% for i in range(mod|length) %}={% endfor %}{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+
+   {% if '__init__' in methods %}
+     {% set caught_result = methods.remove('__init__') %}
+   {% endif %}
+
+   {% block attributes_documentation %}
+   {% if attributes %}
+
+   .. raw:: html
+
+      <a class="attr-details-header collapse-header" data-toggle="collapse" href="#attrDetails" aria-expanded="false" aria-controls="attrDetails">
+         <h2 style="font-size: 24px;">
+            <i class="fas fa-angle-down rotate" style="float: right;"></i> Attributes
+         </h2>
+      </a>
+      <div class="collapse" id="attrDetails">
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+   {%- endfor %}
+
+   .. raw:: html
+
+      </div>
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_documentation %}
+   {% if methods %}
+
+   .. raw:: html
+
+      <a class="meth-details-header collapse-header" data-toggle="collapse" href="#methDetails" aria-expanded="false" aria-controls="methDetails">
+         <h2 style="font-size: 24px;">
+            <i class="fas fa-angle-down rotate" style="float: right;"></i> Methods
+         </h2>
+      </a>
+      <div class="collapse" id="methDetails">
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% for item in methods %}
+   .. automethod:: {{ item }}
+   {%- endfor %}
+
+   .. raw:: html
+
+      </div>
+
+   {% endif %}
+   {% endblock %}
+
+   .. raw:: html
+
+      <script type="text/javascript">
+         $(".collapse-header").click(function () {
+             $(this).children('h2').eq(0).children('i').eq(0).toggleClass("up");
+         })
+      </script>

docs/_templates/autosummary_core/module.rst

@@ -0,0 +1,48 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{% if module.split(".")[1:] | length >= 1 %}
+   {% set mod = module.split(".")[1:] | join(".") %}
+   {% set mod = "jet." + mod %}
+{% else %}
+   {% set mod = "jet" %}
+{% endif %}
+
+{{ mod }}.{{ objname }}
+={% for i in range(mod|length) %}={% endfor %}{{ underline }}
+
+.. automodule:: {{ fullname }}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: Functions
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: Classes
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: Exceptions
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

docs/code/jet.rst

@@ -0,0 +1,14 @@
+jet
+===
+
+.. currentmodule:: jet
+
+.. automodapi:: jet
+    :no-heading:
+    :include-all-objects:
+    :skip: version
+    :skip: TaskBasedContractorType
+    :skip: TensorNetworkFileType
+    :skip: TensorNetworkSerializerType
+    :skip: TensorNetworkType
+    :skip: TensorType