Update documentation and add release notes (Qiskit#214)

* Update documentation and add release notes

This commit updates the documentation theme to match the current theme
that the qiskit project is using. It also takes the opportunity to add
the release notes to the documentation. We previously were only
publishing the release documentation on the github release page which
has limitations. Moving forward we'll use reno to automate the
generation of release notes.

* Use a full clone in docs job for reno

* Finish converting existing release documentation to sphinx rst

* Update contributing guide with reno details

* Add contributing guide to the documentation

* Add note about rustfmt to tox lint contributing section

* Apply suggestions from code review

Co-authored-by: Corey Mendell <[email protected]>

* Rework release note section titles to be consistent with reno's section titles

* Add contributing to sdist to fix CI job

* Add missing contributing rst file

Co-authored-by: Corey Mendell <[email protected]>

.github/workflows/main.yml

@@ -108,6 +108,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v2
         with:

CONTRIBUTING.md

@@ -1,10 +1,14 @@
 # Contributing
 
-First read the overall project contributing guidelines. These are all
-included in the qiskit documentation:
+First read the overall Qiskit project contribution guidelines. These are all
+included in the Qiskit documentation:
 
 https://qiskit.org/documentation/contributing_to_qiskit.html
 
+While it's not all directly applicable since most of it is about the Qiskit
+project itself and retworkx is an independent library developed in tandem
+with Qiskit; the general guidelines and advice still apply here.
+
 ## Contributing to retworkx
 
 In addition to the general guidelines there are specific details for
@@ -28,6 +32,48 @@ the root of the repo, this is because retworkx packaging shim will conflict
 with imports from retworkx the installed version of retworkx (which contains
 the compiled extension).
 
+### Style
+
+#### Rust
+
+Rust is the primary language of retworkx and all the functional code in the
+libraries is written in Rust. The Rust code in retworkx uses
+[rustfmt](https://github.com/rust-lang/rustfmt) to enfore consistent style.
+CI jobs are configured to ensure to check this. Luckily adapting your code is
+as simple as running:
+
+```bash
+cargo fmt
+```
+
+locally. This will automatically restyle the rust code in retworkx to match
+what CI is checking.
+
+##### Lint
+
+An additional step is to run [clippy](https://github.com/rust-lang/rust-clippy)
+on your changes. While this is not run in CI (because it's very dependent on
+the rust/cargo version) it can often catch issues in your code. You can run it
+by running:
+
+```bash
+cargo clippy
+```
+
+#### Python
+
+Python is used primarily for tests and some small pieces of packaging
+and namespace configuration code in the actual library.
+[flake8](https://flake8.pycqa.org/en/latest/) is used to enforce consistent
+style in the python code in the repository. You can run it via tox using:
+
+```bash
+tox -elint
+```
+
+This will also run `cargo fmt` in check mode to ensure that you ran `cargo fmt`
+and will fail if the Rust code doesn't conform to the style rules.
+
 ### Building documentation
 
 Just like with tests building documentation is done via tox. This will handle
@@ -38,3 +84,131 @@ tox -edocs
 ```
 which will output the html rendered documentation in `docs/build/html` which
 you can view locally in a web browser.
+
+### Release Notes
+
+It is important to document any end user facing changes when we release a new 
+version of retworkx.  The expectation is that if your code contribution has 
+user facing changes that you will write the release documentation for these 
+changes. This documentation must explain what was changed, why it was changed, 
+and how users can either use or adapt to the change. The idea behind release 
+documentation is that when a naive user with limited internal knowledge of the 
+project is upgrading from the previous release to the new one, they should be  
+able to read the release notes, understand if they need to update their 
+program which uses retworkx, and how they would go about doing that. It 
+ideally should explain why they need to make this change too, to provide the 
+necessary context.
+
+To make sure we don't forget a release note or if the details of user facing
+changes over a release cycle we require that all user facing changes include
+documentation at the same time as the code. To accomplish this we use the
+[reno](https://docs.openstack.org/reno/latest/) tool which enables a git based
+workflow for writing and compiling release notes.
+
+#### Adding a new release note
+
+Making a new release note is quite straightforward. Ensure that you have reno
+installed with::
+
+    pip install -U reno
+
+Once you have reno installed you can make a new release note by running in
+your local repository checkout's root::
+
+    reno new short-description-string
+
+where short-description-string is a brief string (with no spaces) that describes
+what's in the release note. This will become the prefix for the release note
+file. Once that is run it will create a new yaml file in releasenotes/notes.
+Then open that yaml file in a text editor and write the release note. The basic
+structure of a release note is restructured text in yaml lists under category
+keys. You add individual items under each category and they will be grouped
+automatically by release when the release notes are compiled. A single file
+can have as many entries in it as needed, but to avoid potential conflicts
+you'll want to create a new file for each pull request that has user facing
+changes. When you open the newly created file it will be a full template of
+the different categories with a description of a category as a single entry
+in each category. You'll want to delete all the sections you aren't using and
+update the contents for those you are. For example, the end result should
+look something like::
+
+```yaml
+features:
+  - |
+    Added a new function, :func:`~retworkx.foo` that adds support for doing
+    something to :class:`~retworkx.PyDiGraph` objects. 
+  - |
+    The :class:`~retworkx.PyDiGraph` class has a new method
+    :meth:`~retworkx.PyDiGraph.foo``. This is the equivalent of calling the
+    :func:`~retworkx.foo` function to do something to your
+    :class:`~retworkx.PyDiGraph` object, but provides the convenience of running
+    it natively on an object. For example::
+
+      from retworkx import PyDiGraph
+
+      g = PyDiGraph.
+      g.foo()
+
+deprecations:
+  - |
+    The ``retworkx.bar`` function has been deprecated and will be removed in a
+    future release. It has been superseded by the
+    :meth:`~retworkx.PyDiGraph.foo` method and :func:`~retworkx.foo` function
+    which provides similar functionality but with more accurate results and
+    better performance. You should update your calls
+    ``retworkx.bar()`` calls to use ``retworkx.foo()`` instead.
+```
+
+You can also look at other release notes for other examples.
+
+You can use any
+[sphinx feature](https://www.sphinx-doc.org/en/3.x/usage/restructuredtext/)
+in them (code sections, tables, enumerated lists, bulleted list, etc) to express
+what is being changed as needed. In general you want the release notes to
+include as much detail as needed so that users will understand what has changed,
+why it changed, and how they'll have to update their code.
+
+After you've finished writing your release notes you'll want to add the note
+file to your commit with `git add` and commit them to your PR branch to make
+sure they're included with the code in your PR.
+
+##### Linking to issues
+
+If you need to link to an issue or other Github artifact as part of the release
+note this should be done using an inline link with the text being the issue
+number. For example you would write a release note with a link to issue 12345
+as:
+
+```yaml
+fixes:
+  - |
+    Fixes a race condition in the function ``foo()``. Refer to
+    `#12345 <https://github.com/Qiskit/retworkx/issues/12345>`__ for more
+    details.
+```
+
+#### Generating the release notes
+
+After release notes have been added if you want to see what the full output of
+the release notes. Reno is used to combine the release note yaml files into a
+single rst (ReStructuredText) document that
+[sphinx](https://www.sphinx-doc.org/en/master/) will then compile for us as part
+of the documentation builds. If you want to generate the rst file you
+use the ``reno report`` command. If you want to generate the full retworkx
+release notes for all releases (since we started using reno during 0.8) you just
+run::
+
+    reno report
+
+but you can also use the ``--version`` argument to view a single release (after
+it has been tagged::
+
+    reno report --version 0.8.0
+
+#### Building release notes locally
+
+Building the release notes is part of the standard retworkx documentation
+builds. To check what the rendered html output of the release notes will look
+like for the current state of the repo you can run: `tox -edocs` which will
+build all the documentation into `docs/_build/html` and the release notes in
+particular will be located at `docs/_build/html/release_notes.html`

docs/source/CONTRIBUTING.md

@@ -0,0 +1 @@
+.. mdinclude:: ../../CONTRIBUTING.md

docs/source/conf.py

@@ -32,6 +32,7 @@
               'sphinx.ext.viewcode',
               'm2r2',
               'jupyter_sphinx.execute',
+              'reno.sphinxext',
              ]
 html_static_path = ['_static']
 templates_path = ['_templates']
@@ -122,14 +123,13 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'qiskit_sphinx_theme'
 
 html_theme_options = {
     'logo_only': False,
     'display_version': True,
     'prev_next_buttons_location': 'bottom',
     'style_external_links': True,
-    'style_nav_header_background': '#212121',
 }
 
 # Theme options are theme-specific and customize the look and feel of a theme

docs/source/index.rst

@@ -9,6 +9,8 @@ Contents:
 
    README
    Retworkx API <api>
+   Release Notes <release_notes>
+   Contributing Guide <CONTRIBUTING>
 
 .. Hiding - Indices and tables
    :ref:`genindex`