Add docs infrastructure

.github/workflows/deploy-docs.yml

@@ -0,0 +1,56 @@
+# This code is part of a Qiskit project.
+#
+# (C) Copyright IBM 2023.
+#
+# 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.
+
+name: Deploy Docs
+
+on:
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.repository }}-${{ github.ref }}-${{ github.head_ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
+jobs:
+  docs_publish:
+    if: ${{ startsWith(github.ref, 'refs/heads/stable') && contains('["mtreinish","Cryoris","ElePT","woodsp-ibm"]', github.actor) }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest]
+        python-version: [3.8]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: ./.github/actions/install-optimization
+        with:
+          os: ${{ matrix.os }}
+      - name: Install Dependencies
+        run: |
+          pip install jupyter qiskit-terra[visualization]
+          sudo apt-get install -y pandoc graphviz
+        shell: bash
+      - name: Build and publish
+        env:
+          encrypted_rclone_key: ${{ secrets.encrypted_rclone_key }}
+          encrypted_rclone_iv: ${{ secrets.encrypted_rclone_iv }}
+          QISKIT_PARALLEL: False
+          QISKIT_DOCS_BUILD_TUTORIALS: 'always'
+        run: |
+          echo "earliest_version: 0.1.0" >> releasenotes/config.yaml
+          tools/ignore_untagged_notes.sh
+          make html
+          tools/deploy_documentation.sh
+        shell: bash

.github/workflows/main.yml

@@ -66,16 +66,38 @@ jobs:
         run: |
           sudo apt-get -y install pandoc graphviz python3-enchant hunspell-en-us
           pip install pyenchant
-          echo "earliest_version: 0.1.0" >> releasenotes/config.yaml
         shell: bash
       - run: pip check
         if: ${{ !cancelled() }}
         shell: bash
+      - name: Copyright Check
+        run: |
+          python tools/check_copyright.py -check
+        if: ${{ !cancelled() }}
+        shell: bash
       - name: Style Check
         run: |
           make style
         if: ${{ !cancelled() }}
         shell: bash
+      - name: Run make html
+        run: |
+          make clean_sphinx
+          make html
+          cd docs/_build/html
+          mkdir artifacts
+          tar -zcvf artifacts/documentation.tar.gz --exclude=./artifacts .
+        if: ${{ !cancelled() }}
+        shell: bash
+      - name: Run upload documentation
+        uses: actions/upload-artifact@v3
+        with:
+          name: documentation
+          path: docs/_build/html/artifacts/documentation.tar.gz
+        if: ${{ !cancelled() }}
+      - run: make doctest
+        if: ${{ !cancelled() }}
+        shell: bash
   Algorithms:
     runs-on: ${{ matrix.os }}
     strategy:
@@ -129,6 +151,54 @@ jobs:
         with:
           name: ${{ matrix.os }}-${{ matrix.python-version }}
           path: ./ci-artifact-data/*
+  Tutorials:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ ubuntu-latest ]
+        python-version: [ 3.8, 3.11 ]
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+          cache-dependency-path: |
+            setup.py
+            requirements.txt
+            requirements-dev.txt
+      - uses: ./.github/actions/install-main-dependencies
+        with:
+          os: ${{ matrix.os }}
+          python-version: ${{ matrix.python-version }}
+        if: ${{ !startsWith(github.ref, 'refs/heads/stable') && !startsWith(github.base_ref, 'stable/') }}
+      - uses: ./.github/actions/install-algorithms
+        with:
+          os: ${{ matrix.os }}
+      - name: Install Dependencies
+        run: |
+          pip install jupyter qiskit-terra[visualization]
+          sudo apt-get install -y pandoc graphviz
+        shell: bash
+      - name: Run Qiskit Algorithms Tutorials
+        env:
+          QISKIT_PARALLEL: False
+          QISKIT_DOCS_BUILD_TUTORIALS: 'always'
+        run: |
+          tools/ignore_untagged_notes.sh
+          make html
+          cd docs/_build/html
+          mkdir artifacts
+          tar -zcvf artifacts/tutorials.tar.gz --exclude=./artifacts .
+        shell: bash
+      - name: Run upload tutorials
+        uses: actions/upload-artifact@v3
+        with:
+          name: tutorials${{ matrix.python-version }}
+          path: docs/_build/html/artifacts/tutorials.tar.gz
   Deprecation_Messages_and_Coverage:
     needs: [Checks, Algorithms]
     runs-on: ubuntu-latest

Makefile

@@ -35,9 +35,9 @@ endif
 # You can set this variable from the command line.
 SPHINXOPTS    =
 
-.PHONY: lint style black test test_ci spell copyright coverage clean
+.PHONY: lint style black test test_ci spell copyright html doctest clean_sphinx coverage clean
 
-all_check: spell style lint copyright
+all_check: spell style lint copyright clean_sphinx html doctest
 
 lint:
 	pylint -rn qiskit_algorithms test tools
@@ -58,10 +58,20 @@ test_ci:
 
 spell:
 	pylint -rn --disable=all --enable=spelling --spelling-dict=en_US --spelling-private-dict-file=.pylintdict qiskit_algorithms test tools
+	sphinx-build -M spelling docs docs/_build -W -T --keep-going $(SPHINXOPTS)
 
 copyright:
 	python tools/check_copyright.py
 
+html:
+	sphinx-build -M html docs docs/_build -W -T --keep-going $(SPHINXOPTS)
+
+doctest:
+	sphinx-build -M doctest docs docs/_build -W -T --keep-going $(SPHINXOPTS)
+
+clean_sphinx:
+	make -C docs clean
+
 coverage:
 	coverage3 run --source qiskit_algorithms -m unittest discover -s test -q
 	coverage3 report

docs/Makefile

@@ -0,0 +1,28 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2023.
+#
+# 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.
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/nbsphinx-gallery.css

@@ -0,0 +1,31 @@
+.nbsphinx-gallery {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+    gap: 5px;
+    margin-top: 1em;
+    margin-bottom: 1em;
+}
+
+.nbsphinx-gallery>a {
+    padding: 5px;
+    border: 1px dotted currentColor;
+    border-radius: 2px;
+    text-align: center;
+}
+
+.nbsphinx-gallery>a:hover {
+    border-style: solid;
+}
+
+.nbsphinx-gallery img {
+    max-width: 100%;
+    max-height: 100%;
+}
+
+.nbsphinx-gallery>a>div:first-child {
+    display: flex;
+    align-items: start;
+    justify-content: center;
+    height: 120px;
+    margin-bottom: 5px;
+}

docs/_templates/autosummary/class.rst

@@ -0,0 +1,31 @@
+{#
+   We show all the class's methods and attributes on the same page. By default, we document
+   all methods, including those defined by parent classes.
+-#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

docs/_templates/autosummary/class_no_inherited_members.rst

@@ -0,0 +1,28 @@
+{# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#}
+
+{{ objname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :show-inheritance:
+
+{% block attributes_summary %}
+  {% if attributes %}
+   .. rubric:: Attributes
+    {% for item in attributes %}
+   .. autoattribute:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock -%}
+
+{% block methods_summary %}
+  {% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %}
+  {% if wanted_methods %}
+   .. rubric:: Methods
+    {% for item in wanted_methods %}
+   .. automethod:: {{ item }}
+    {%- endfor %}
+  {% endif %}
+{% endblock %}

docs/apidocs/algorithms.rst

@@ -0,0 +1,6 @@
+.. _qiskit-algorithms:
+
+.. automodule:: qiskit_algorithms
+   :no-members:
+   :no-inherited-members:
+   :no-special-members: