Issue #5 | Documentation: sphinx docs and action for GH Pages

.github/workflows/docs.yml

@@ -0,0 +1,31 @@
+name: Build and deploy sphinx docs
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+      - 'stable/**'
+
+jobs:
+  build_and_deploy_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: '3.9'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+          sudo apt-get update
+          sudo apt-get install -y pandoc
+      - name: Build docs
+        run: |
+          tox -edocs
+      - name: Deploy docs
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_build/html/

.gitignore

@@ -47,3 +47,7 @@ coverage.xml
 
 # virtualenv
 ENV/
+
+# Sphinx
+docs/stubs/
+docs/_build/

docs/_static/custom.css

@@ -0,0 +1,27 @@
+.toggle .header {
+    display: block;
+    clear: both;
+    background-color: #785EF0;
+    color: #f9f9f9;
+    height: 40px;
+    padding-top: 10px;
+    padding-left: 5px;
+    margin-bottom: 20px;
+}
+
+.toggle .header:before {
+    float: left;
+    content: "▶ ";
+    font-size: 20px;
+
+}
+
+.toggle .header.open:before {
+    float: left;
+    content: "▼ ";
+    font-size: 20px;
+}
+
+.toggle{
+  background: #FBFBFB;
+}

docs/apidocs/index.rst

@@ -0,0 +1,12 @@
+.. qiskit_braket_plugin:
+
+.. module:: qiskit_braket_plugin
+
+===================================
+Qiskit-Braket Plugin API References
+===================================
+
+.. toctree::
+   :maxdepth: 2
+
+   providers

docs/apidocs/providers.rst

@@ -0,0 +1,4 @@
+.. automodule:: qiskit_braket_plugin.providers
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:

docs/conf.py

@@ -0,0 +1,73 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2022.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# pylint: disable=invalid-name
+
+"""
+Sphinx documentation builder
+"""
+
+# General options:
+import os
+
+project = "Qiskit-Braket plugin."
+copyright = "2022"  # pylint: disable=redefined-builtin
+author = ""
+
+# The full version, including alpha/beta/rc tags
+with open(
+    os.path.join(
+        os.path.dirname(os.path.abspath(__file__)),
+        "..",
+        "qiskit_braket_plugin",
+        "VERSION.txt",
+    ),
+    "r",
+) as f:
+    release = f.read()
+# The short X.Y version
+version = release
+
+extensions = [
+    "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.extlinks",
+    "jupyter_sphinx",
+    "sphinx_autodoc_typehints",
+    "reno.sphinxext",
+    "nbsphinx",
+]
+templates_path = ["_templates"]
+numfig = True
+numfig_format = {"table": "Table %s"}
+language = None
+pygments_style = "colorful"
+add_module_names = False
+modindex_common_prefix = ["qiskit_braket_plugin."]
+
+# html theme options
+html_static_path = ["_static"]
+html_logo = "_static/images/logo.png"
+
+# autodoc/autosummary options
+autosummary_generate = True
+autosummary_generate_overwrite = False
+autoclass_content = "both"
+
+# nbsphinx options (for tutorials)
+nbsphinx_timeout = 180
+nbsphinx_execute = "always"
+nbsphinx_widgets_path = ""
+exclude_patterns = ["_build", "**.ipynb_checkpoints"]

docs/how_tos/index.rst

@@ -0,0 +1,4 @@
+.. nbgallery::
+   :glob:
+
+   *

docs/index.rst

@@ -0,0 +1,17 @@
+##################################
+Qiskit-Braket plugin documentation
+##################################
+
+Qiskit-Braket plugin to execute Qiskit programs on AWS quantum computing hardware devices through Amazon Braket.
+
+.. toctree::
+  :maxdepth: 2
+
+  Tutorials <tutorials/index>
+  User Guide <how_tos/index>
+  API References <apidocs/index>
+
+.. Hiding - Indices and tables
+   :ref:`genindex`
+   :ref:`modindex`
+   :ref:`search`

docs/tutorials/index.rst

@@ -0,0 +1,4 @@
+.. nbgallery::
+   :glob:
+
+   *

qiskit_braket_plugin/VERSION.txt

@@ -0,0 +1 @@
+0.0.0

qiskit_braket_plugin/__init__.py

@@ -0,0 +1 @@
+"""Qiskit-Braket plugin."""

qiskit_braket_plugin/providers/__init__.py

@@ -1,4 +1,24 @@
-"""Providers module."""
+"""
+=======================================================
+Provider module (:mod:`qiskit_braket_plugin.providers`)
+=======================================================
+
+.. currentmodule:: qiskit_braket_plugin.providers
+
+Provider module contains classes and functions to connect
+AWS Braket abstraction to Qiskit architecture.
+
+Provider classes and functions
+==============================
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    AWSBraketBackend
+    BraketLocalBackend
+    AWSBraketProvider
+    AWSBraketJob
+"""
 
 from .braket_backend import AWSBraketBackend, BraketLocalBackend
 from .braket_provider import AWSBraketProvider

qiskit_braket_plugin/providers/braket_backend.py

@@ -71,7 +71,7 @@ def run(self, run_input, **options):
 
 
 class AWSBraketBackend(BraketBackend):
-    """BraketBackend."""
+    """AWSBraketBackend."""
 
     def __init__(  # pylint: disable=too-many-arguments
         self,

requirements-dev.txt

@@ -6,6 +6,10 @@ pytest>=6.2.5
 mypy>=0.780
 mypy-extensions>=0.4.3
 tox==3.24.5
+jupyter-sphinx>=0.3.2
+nbsphinx>=0.8.8
+sphinx-autodoc-typehints>=1.17.0
+reno>=3.5.0
 # Black's formatting rules can change between major versions, so we use
 # the ~= specifier for it.
 black[jupyter]~=22.1

tox.ini

@@ -1,6 +1,6 @@
 [tox]
 minversion = 2.1
-envlist = py37, py38, py39, py310, lint, coverage
+envlist = py37, py38, py39, py310, lint, coverage, docs
 skipsdist = true
 
 [testenv]
@@ -36,3 +36,9 @@ commands =
   coverage3 run --source qiskit_braket_plugin --parallel-mode -m pytest
   coverage3 combine
   coverage3 report --fail-under=80
+
+[testenv:docs]
+deps =
+    -r{toxinidir}/requirements-dev.txt
+commands =
+  sphinx-build -b html -W {posargs} docs/ docs/_build/html