Skip to content

Latest commit

 

History

History
262 lines (189 loc) · 8.05 KB

CONTRIBUTING_DOCS.md

File metadata and controls

262 lines (189 loc) · 8.05 KB

Contributing to the Documentation

This is the Contributors guide for the documentation of Mitiq, the Python toolkit for implementing error mitigation on quantum computers.

Python Build PyPI version Unitary Fund

Requirements

The documentation is generated with Sphinx. The necessary packages can be installed, from the root mitiq directory

pip install -e .
pip install -r requirements.txt

as they are present in the requirements.txt file. Otherwise, with

pip install -U sphinx m2r sphinxcontrib-bibtex pybtex sphinx-copybutton sphinx-autodoc-typehints

m2r allows to include .md files, besides .rst, in the documentation. sphinxcontrib-bibtex allows to include citations in a .bib file and pybtex allows to customize how they are rendered, e.g., APS-style. sphinx-copybutton allows to easily copy-paste code snippets from examples. sphinx-autodoc-typehints allows to control how annotations are displayed in the API-doc part of the documentation, integrating with sphinx-autodoc and sphinx-napoleon.

You can check that Sphinx is installed with sphinx-build --version.

In addition, there are two requirements, tensorflow and tensorflow-quantum, which are used solely in guide/guide-executors.rst. They can be installed via:

pip install -r docs/requirements.txt

If they are not installed, the test that uses them will be skipped. We do this because tensorflow-quantum has incompatibility issues -- version 0.4.0 works on py38 but not Windows, and version 0.3.1 works on Windows but not py38. Therefore, these two requirements cannot be installed on Windows. See gh-419 for more information.

How to Update the Documentation

The configuration file

  • Since the documentation is already created, you need not to generate a configuration file from scratch (this is done with sphinx-quickstart). Meta-data, extentions and other custom specifications are accounted for in the conf.py file.

Add features in the conf.py file

  • To add specific feature to the documentation, extensions can be include. For example to add classes and functions to the API doc, make sure that autodoc extension is enabled in the conf.py file, and for tests the doctest one,
extensions = ['sphinx.ext.autodoc','sphinx.ext.doctest']

Update the guide with a tree of restructured text files

You need not to modify the docs/build folder, as it is automatically generated. You will modify only the docs/source files.

The documentation is divided into a guide, whose content needs to be written from scratch, and an API-doc part, which can be partly automatically generated.

  • To add information in the guide, it is possible to include new information as a restructured text (.rst) or markdown (.md) file.

The main file is index.rst. It includes a guide.rst and an apidoc.rst file, as well as other files. Like in LaTeX, each file can include other files. Make sure they are included in the table of contents

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   changelog.rst

You can include markdown files in the guide

  • Information to the guide can also be added from markdown (.md) files, since m2r (pip install --upgrade m2r) is installed and added to the conf.py file (extensions = ['m2r']). Just add the .md file to the toctree.

To include .md files outside of the documentation source directory, you can add in source an .rst file to the toctree that contains inside it the .. mdinclude:: ../file.md command, where file.md is the one to be added.

Automatically add information to the API doc

  • New modules, classes and functions can be added by listing them in the appropriate .rst file (such as autodoc.rst or a child), e.g.,
Factories
---------
.. automodule:: mitiq.factories
   :members:

will add all elements of the mitiq.factories module. One can hand-pick classes and functions to add, to comment them, as well as exclude them.

Build the documentation locally

  • To build the documentation, from bash, move to the docs folder and run
sphinx-build -b html source build

this generates the docs/build folder. This folder is not kept track of in the github repository, as docs/build is present in the .gitignore file.

The html and latex and pdf files will be automatically created in the docs/build folder.

Create the html

  • To create the html structure,
make html

Create the pdf

  • To create the latex files and output a pdf,
make latexpdf

How to Test the Documentation Examples

There are several ways to check that the documentation examples work. Currently, mitiq is testing them with the doctest extension of sphinx. This is set in the conf.py file and is executed with

make doctest

from the mitiq/docs directory. From the root directory mitiq, simply run

make docs

to obtain the same result.

These equivalent commands test the code examples in the guide and ".rst" files, as well as testing the docstrings, since these are imported with the autodoc extension.

When writing a new example, you can use different directives in the rst file to include code blocks. One of them is

.. code-block:: python

   1+1        # simple example

In order to make sure that the block is parsed with make doctest, use the testcode directive. This can be used in pair with testoutput, if something is printed, and, eventually testsetup, to import modules or set up variables in an invisible block. An example is:

.. testcode:: python

   1+1        # simple example

with no output and

.. testcode:: python

   print(1+1)        # explicitly print

.. testoutput:: python

   2        # match the print message

The use of testsetup allows blocks that do not render:

.. testsetup:: python

   import numpy as np  # this block is not rendered in the html or pdf

.. testcode:: python

   np.array(2)

.. testoutput:: python

   array(2)

There is also the doctest directive, which allows to include interactive Python blocks. These need to be given this way:

.. doctest:: python

   >>> import numpy as np
   >>> print(np.array(2))
   array(2)

Notice that no space is left between the last input and the output.

A way to test docstrings without installing sphinx is with pytest + doctest:

pytest --doctest-glob='*.rst'

or alternatively

pytest --doctest-modules

However, this only checks doctest blocks, and does not recognize testcode blocks. Moreover, it does not parse the conf.py file nor uses sphinx. A way to include testing of testcode and testoutput blocks is with the pytest-sphinx plugin. Once installed,

pip install pytest-sphinx

it will show up as a plugin, just like pytest-coverage and others, simply calling

pytest --doctest-glob='*.rst'

The pytest-sphinx plugin does not support testsetup directives.

In order to skip a test, if this is problematic, one can use the SKIP and IGNORE keywords, adding them as comments next to the relevant line or block:

>>> something_that_raises()  # doctest: +IGNORE

One can also use various doctest features by configuring them in the docs/pytest.ini file.

Additional information

Here are some notes on how to build docs.

Here is a cheat sheet for restructed text formatting, e.g. syntax for links etc.