Redesign documentation

[mariaschuld]

This is a major re-design of the plugin's documentation, integrating it into the pennylane.ai webpage. It is best reviewed by building the docs locally, since so many files are changed.

I propose this format for all plugins, and it should therefore be regarded as a potential template for plugin docs (for those plugins hosted by Xanadu).

Possible issues:
I copied the xanadu theme over to here, but I am not 100% familiar with what is needed from the theme.

[codecov]

Codecov Report

Merging #78 into master will not change coverage by %.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master      #78   +/-   ##
=======================================
  Coverage   99.11%   99.11%           
=======================================
  Files           7        7           
  Lines         340      340           
=======================================
  Hits          337      337           
  Misses          3        3           

Impacted Files	Coverage Δ
pennylane_qiskit/aer.py	100.00% <ø> (ø)
pennylane_qiskit/basic_aer.py	100.00% <ø> (ø)
pennylane_qiskit/converter.py	100.00% <ø> (ø)
pennylane_qiskit/ibmq.py	100.00% <ø> (ø)
pennylane_qiskit/qiskit_device.py	98.62% <ø> (ø)

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 269802a...b8c5e20. Read the comment docs.

[mariaschuld]

The failing test may be related to qiskit server problems, see Issue from 11 hours ago: Qiskit/qiskit-ibmq-provider#617

[josh146]

Looks great!

[mariaschuld]

Thanks @josh146 for your great contributions.

Let's see what @antalszava thinks about the new layout.

[josh146]

Something that has crossed my mind: the API part of the documentation still uses the old style documentation (entire module on one page) as opposed to the new-style (one page per class).

This should be relatively easy, and might make it more maintainable:

The git diff is just:

diff --git a/doc/code/pennylane_qiskit.rst b/doc/code/pennylane_qiskit.rst
new file mode 100644
index 0000000..d1b9aab
--- /dev/null
+++ b/doc/code/pennylane_qiskit.rst
@@ -0,0 +1,8 @@
+pennylane-qiskit
+================
+
+.. currentmodule:: pennylane_qiskit
+
+.. automodapi:: pennylane_qiskit
+    :no-heading:
+    :include-all-objects:
diff --git a/doc/conf.py b/doc/conf.py
index d900e7c..2d4d698 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -40,9 +40,15 @@ extensions = [
     'sphinx.ext.inheritance_diagram',
     "sphinx.ext.intersphinx",
     'sphinx.ext.viewcode',
+    "sphinx_automodapi.automodapi",
     'edit_on_github'
 ]

+autosummary_generate = True
+autosummary_imported_members = False
+automodapi_toctreedirnm = "code/api"
+automodsumm_inherited_members = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates', 'xanadu_theme']

diff --git a/doc/index.rst b/doc/index.rst
index 0ee9e29..046768f 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -44,7 +44,4 @@ PennyLane-Qiskit Plugin
    :caption: API
    :hidden:

-   code/qiskit_device
-   code/basic_aer
-   code/aer
-   code/ibmq
+   code/pennylane_qiskit
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 30aa0f4..5fd9be7 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -6,3 +6,4 @@ pybind11
 qiskit
 git+https://github.com/XanaduAI/pennylane.git#egg=pennylane
 dc-qiskit-algorithms
+sphinx-automodapi

The downside is that everything will be documented, and we have less control over the look, what is included, etc. So I'm on the fence with this.

[mariaschuld]

I'm in favour - the API is really only useful for developers, since users never really instantiate a class (they use the device). So it makes sense to document everything public.

Can you just push the change?

Maybe we should add a comment to the module docstring saying that the classes are automatically created when calling qml.device('qiskit.XXX',...)?

[josh146]

Can you just push the change?

Done in 4e52c12 :)

[antalszava]

@mariaschuld this is awesome, thank you so much! 💯 😊 Looks really neat! I had a couple of suggestions & questions, though none of them was major