Prepares the code base for stable development (#65)

* docs: some contribution guideline updates * ci: do not auto-publish docs from `main` * docs: setup reno * docs: remove "under development" warnings * docs: update documentation landing page * docs: update README * docs: fix image preview dimensions * docs: update readme image * docs: update intro paragraph
qiskit-community · Jul 18, 2024 · 93b0737 · 93b0737
1 parent 3d84aa4
commit 93b0737
Show file tree

Hide file tree

Showing 20 changed files with 84 additions and 52 deletions.
diff --git a/.github/workflows/publish_docs.yml b/.github/workflows/publish_docs.yml
@@ -2,9 +2,6 @@ name: Publish Sphinx docs
 
 on:
   workflow_dispatch:
-  push:
-    branches:
-      - main
 
 jobs:
   build:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -48,6 +48,8 @@ This will run the following tools:
 - [`mypy`](https://mypy.readthedocs.io/en/stable/): to check our type hints
 - [`pylint`](https://pylint.readthedocs.io/en/stable/): for additional linting
   rules
+- [`typos`](https://github.com/crate-ci/typos): to avoid simple typos
+- [`reno`](https://docs.openstack.org/reno/latest/): will lint all release notes
 
 Note, that `tox` will stop as soon as the first linter fails. So after fixing
 one, be sure to re-run the linting check to see if the other tools will pass.
@@ -79,6 +81,15 @@ for example, for selecting a subset of tests to run, like so:
 tox -e py311 -- <path/to/test_file.py>
 ```
 
+### Doctest
+
+Some docstrings contain executable code examples. These can be tested via
+[`doctest`](https://docs.python.org/3/library/doctest.html), for which we also
+have a simple job script:
+```
+tox -e doctest
+```
+
 #### Coverage
 
 We strive towards complete coverage of our unittest suite. This means, we want
@@ -98,3 +109,30 @@ We also test the execution of our Jupyter notebooks using
 ```
 tox -e notebook
 ```
+
+### Documentation
+
+If you are working on the documentation, you should also check that Sphinx is
+able to build it and that all the formatting renders properly. To do so, simply
+run this:
+```
+tox -e docs
+```
+
+If you want to start from a fresh build of the documentation, simply run:
+```
+tox -e docs-clean
+```
+And then rebuild the docs.
+
+### Release Notes
+
+When contributing to the code of this repository, you should create a release
+note which documents and explains your changes. To do so, we use the
+[`reno`](https://docs.openstack.org/reno/latest/) tool.
+Simply put, you create a new release note file via:
+```
+reno new <some-descriptive-filename>
+```
+This will output the path to a release note template file which you can then
+edit and commit.
diff --git a/README.md b/README.md
@@ -1,10 +1,18 @@
 # POVMs
 
-A toolbox for the implementation of positive operator-valued measures (POVMs).
-
-> [!WARNING]
-> This toolbox is still in development! Breaking changes to the API may be
-> introduced at any time without prior warning.
+<p align="center">
+  <img src="/docs/_static/read-me-figure.jpg" height="350">
+</p>
+
+This is a toolbox for working with positive operator-valued measures (POVMs).
+It enables users to use POVMs for sampling the state of quantum circuits (see
+also `povm_toolbox.sampler`) and compute expectation values of any observable of
+interest (see also `povm_toolbox.post_processor`).
+The toolbox includes a library of pre-defined POVMs (see `povm_toolbox.library`)
+which provide ready-to-go POVM circuit definitions. You can also implement your
+own POVM circuits by following the provided interface.
+Additionally, you can work with POVMs on a quantum-informational theoretical
+footing (see `povm_toolbox.quantum_info`).
 
 ## Installation
 
@@ -26,11 +34,6 @@ If you intend to develop on this code, you should consider reading the
 You can find the documentation hosted
 [here](https://qiskit-community.github.io/povm-toolbox/).
 
-> [!WARNING]
-> Since this toolbox is still in development, so is its documentation! You may
-> encounter missing information as well as sudden changes from one day to
-> another.
-
 ## Citation
 
 If you use this project, please cite the following reference:

diff --git a/docs/_static/read-me-figure.jpg b/docs/_static/read-me-figure.jpg
diff --git a/docs/apidocs/povm_toolbox.library.metadata.rst b/docs/apidocs/povm_toolbox.library.metadata.rst
@@ -2,9 +2,6 @@
 Metadata
 ========
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-library-metadata:
 
 .. automodule:: povm_toolbox.library.metadata

diff --git a/docs/apidocs/povm_toolbox.library.povm_implementation.rst b/docs/apidocs/povm_toolbox.library.povm_implementation.rst
@@ -2,9 +2,6 @@
 POVMImplementation
 ==================
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-library-povm_implementation:
 
 .. automodule:: povm_toolbox.library.povm_implementation

diff --git a/docs/apidocs/povm_toolbox.library.rst b/docs/apidocs/povm_toolbox.library.rst
@@ -2,9 +2,6 @@
 Library
 =======
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-library:
 
 .. automodule:: povm_toolbox.library

diff --git a/docs/apidocs/povm_toolbox.post_processor.rst b/docs/apidocs/povm_toolbox.post_processor.rst
@@ -2,9 +2,6 @@
 Post Processor
 ==============
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-post_processor:
 
 .. automodule:: povm_toolbox.post_processor

diff --git a/docs/apidocs/povm_toolbox.quantum_info.base.rst b/docs/apidocs/povm_toolbox.quantum_info.base.rst
@@ -2,9 +2,6 @@
 Interfaces
 ==========
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-quantum_info-base:
 
 .. automodule:: povm_toolbox.quantum_info.base

diff --git a/docs/apidocs/povm_toolbox.quantum_info.rst b/docs/apidocs/povm_toolbox.quantum_info.rst
@@ -2,9 +2,6 @@
 Quantum Info
 ============
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-quantum_info:
 
 .. automodule:: povm_toolbox.quantum_info

diff --git a/docs/apidocs/povm_toolbox.rst b/docs/apidocs/povm_toolbox.rst
@@ -2,9 +2,6 @@
 POVM Toolbox
 ============
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox:
 
 .. automodule:: povm_toolbox

diff --git a/docs/apidocs/povm_toolbox.sampler.rst b/docs/apidocs/povm_toolbox.sampler.rst
@@ -2,9 +2,6 @@
 Sampler
 =======
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-sampler:
 
 .. automodule:: povm_toolbox.sampler

diff --git a/docs/apidocs/povm_toolbox.utilities.rst b/docs/apidocs/povm_toolbox.utilities.rst
@@ -2,9 +2,6 @@
 Utilities
 =========
 
-.. warning::
-   This API reference is still `under construction`.
-
 .. _povm_toolbox-utilities:
 
 .. automodule:: povm_toolbox.utilities

diff --git a/docs/conf.py b/docs/conf.py
@@ -12,6 +12,7 @@
 
 import os
 import sys
+from importlib.metadata import version as metadata_version
 
 # The following line is required for autodoc to be able to find and import the code whose API should
 # be documented.
@@ -21,7 +22,7 @@
 project_copyright = "2024, IBM Quantum Zurich"
 author = "IBM Quantum Zurich"
 language = "en"
-release = "0.0.0"
+release = metadata_version("povm_toolbox")
 
 html_theme = "qiskit-ecosystem"
 
@@ -49,6 +50,7 @@
     "sphinx.ext.intersphinx",
     "matplotlib.sphinxext.plot_directive",
     "sphinx_copybutton",
+    "reno.sphinxext",
     "nbsphinx",
     "qiskit_sphinx_theme",
     "pytest_doctestplus.sphinx.doctestplus",

diff --git a/docs/index.rst b/docs/index.rst
@@ -2,11 +2,25 @@
 POVM Toolbox
 ############
 
-A toolbox for the implementation of positive operator-valued measures (POVMs).
-
-.. warning::
-   This toolbox is still in development! Breaking changes to the API may be
-   introduced at any time without prior warning.
+.. image:: _static/read-me-figure.jpg
+
+This is a toolbox for working with positive operator-valued measures (POVMs).
+It enables users to use POVMs for sampling the state of quantum circuits (see
+also :mod:`povm_toolbox.sampler`) and compute expectation values of any
+observable of interest (see also :mod:`povm_toolbox.post_processor`).
+The toolbox includes a library of pre-defined POVMs (see
+:mod:`povm_toolbox.library`) which provide ready-to-go POVM circuit definitions.
+You can also implement your own POVM circuits by following the provided
+interface.
+Additionally, you can work with POVMs on a quantum-informational theoretical
+footing (see :mod:`povm_toolbox.quantum_info`).
+
+In this documentation you can find a number of resources including:
+
+- `explanations <explanations/index.html>`_ to learn more about POVMs
+- how to get started with coding using one of the `tutorials <tutorials/index.html>`_
+- dive into more specific features with the `how-to guides <how_tos/index.html>`_
+- and, of course, look up specific details of the `API <apidocs/povm_toolbox.html>`_
 
 Installation
 ------------
@@ -22,12 +36,6 @@ You can install this code via pip:
 Make sure that you have the correct Python environment active, into which you
 want to install this code, before running the above.
 
-Getting started
----------------
-
-Be sure to check out our `tutorials <tutorials/index.html>`_ to get started with this
-toolbox.
-
 Citation
 --------
 
@@ -48,3 +56,4 @@ If you use this project, please cite the following reference:
    Explanations <explanations/index>
    API Reference <apidocs/povm_toolbox>
    GitHub <https://github.com/qiskit-community/povm-toolbox>
+   Release Notes <release-notes>
diff --git a/docs/release-notes.rst b/docs/release-notes.rst
@@ -0,0 +1,3 @@
+.. _release notes:
+
+.. release-notes:: Release Notes
diff --git a/pyproject.toml b/pyproject.toml
@@ -48,6 +48,7 @@ lint = [
     "povm_toolbox[style]",
     "mypy>=1.10.0",
     "pylint>=3.1.0",
+    "reno>=4.1",
     "toml",
 ]
 notebook-dependencies = [
@@ -61,6 +62,7 @@ docs = [
     "sphinx-autodoc-typehints",
     "sphinx-copybutton",
     "nbsphinx",
+    "reno>=4.1",
     "pytest-doctestplus>=1.2.1",
 ]
 

diff --git a/releasenotes/config.yaml b/releasenotes/config.yaml
@@ -0,0 +1,4 @@
+---
+encoding: utf8
+default_branch: main
+unreleased_version_title: "Upcoming release"
diff --git a/releasenotes/notes/.gitkeep b/releasenotes/notes/.gitkeep
diff --git a/tox.ini b/tox.ini
@@ -33,6 +33,7 @@ commands =
   ruff check --preview --extend-select CPY001 povm_toolbox/ test/
   ruff check --select D --ignore D406,D407 povm_toolbox/
   typos
+  reno lint
 
 [testenv:{,py-,py3-,py39-,py310-,py311-,py312-}notebook]
 extras =
-Original file line number
+Diff line change
@@ Expand Up / @@ -2,9 +2,6 @@ name: Publish Sphinx docs @@
     on:
       workflow_dispatch:
-      push:
-        branches:
-          - main
     jobs:
       build:
@@ Expand Down @@
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		.. _release notes:

		.. release-notes:: Release Notes