Another round of README cleanup and improvements (#1168)

.gitlab-ci.yml

@@ -73,6 +73,12 @@ test-py38:
   script:
     - make test
 
+# test for coverage using coveralls
+test-coverage:
+  extends: .python
+  script:
+    - make coverage
+
 ####################################################################################################
 # MASTER-ONLY JOBS
 ####################################################################################################

CHANGELOG.md

@@ -7,7 +7,7 @@ Changelog
 ### Announcements
 
 -   In order to make the pyQuil examples more accessible, we recently made a new
-    repository,[rigetti/forest-tutorials][forest-tutorials], which is set up so
+    repository, [rigetti/forest-tutorials][forest-tutorials], which is set up so
     that the example notebooks can be run via a web browser in a preconfigured
     execution environment on [Binder][mybinder]. The pyQuil README now has a
     "launch binder" badge for running these tutorial notebooks, as well as a
@@ -21,10 +21,12 @@ Changelog
 ### Improvements and Changes
 
 -   Pin the `antlr4-python3-runtime` package to below `v4.8` (@karalekas, gh-1163).
--   Expand upon the [acknowledgements](ACKNOWLEDGEMENTS.md) (@karalekas, gh-1165).
--   Use the [gitlab-pipelines](https://github.com/rigetti/gitlab-pipelines)
+-   Expand upon the [acknowledgements](ACKNOWLEDGEMENTS.md) file to mention
+    contributions from pre-QCS and list previous maintainers (@karalekas, gh-1165).
+-   Use the [rigetti/gitlab-pipelines](https://github.com/rigetti/gitlab-pipelines)
     repository's template YAMLs in the `.gitlab-ci.yml`, and add a section to
     `CONTRIBUTING.md` about the CI/CD pipelines (@karalekas, gh-1166).
+-   Add another round of improvements to the README (@karalekas, gh-1168).
 
 ### Bugfixes
 

Makefile

@@ -34,6 +34,10 @@ config:
 	echo "quilc_address = ${DEFAULT_QUILC_URL}" >> ~/.forest_config
 	cat ~/.forest_config
 
+.PHONY: coverage
+coverage:
+	coveralls
+
 .PHONY: dist
 dist:
 	python setup.py sdist

README.md

@@ -1,20 +1,14 @@
 PyQuil: Quantum programming in Python
 =====================================
 
-[![Binder](https://mybinder.org/badge_logo.svg)][binder]
-[![pipeline status](https://gitlab.com/rigetti/forest/pyquil/badges/master/pipeline.svg)](https://gitlab.com/rigetti/forest/pyquil/commits/master)
-[![docs status](https://readthedocs.org/projects/pyquil/badge/?version=latest)](http://pyquil.readthedocs.io/en/latest/?badge=latest)
-[![pypi downloads](https://img.shields.io/pypi/dm/pyquil.svg)](https://pypi.org/project/pyquil/)
-[![pypi version](https://img.shields.io/pypi/v/pyquil.svg)](https://pypi.org/project/pyquil/)
-[![slack workspace](https://img.shields.io/badge/slack-rigetti--forest-812f82.svg?)][slack_invite]
-[![code-style][black-badge]][black-repo]
-
-[binder]: https://mybinder.org/v2/gh/rigetti/forest-tutorials/master?urlpath=lab/tree/Welcome.ipynb
-[black-repo]: https://github.com/psf/black
-[black-badge]: https://img.shields.io/badge/code%20style-black-000000.svg
-[forest-tutorials]: https://github.com/rigetti/forest-tutorials
-[jupyter]: https://jupyter.org/
-[mybinder]: https://mybinder.org
+[![binder](https://mybinder.org/badge_logo.svg)][binder]
+[![gitlab][gitlab-badge]][gitlab-repo]
+[![docs][docs-badge]][docs-repo]
+[![coverage][coverage-badge]][coverage-repo]
+[![docker][docker-badge]][docker-repo]
+[![pepy][pepy-badge]][pepy-repo]
+[![pypi][pypi-badge]][pypi-repo]
+[![slack][slack-badge]][slack-invite]
 
 PyQuil is a Python library for quantum programming using [Quil](https://arxiv.org/abs/1608.03355),
 the quantum instruction language developed at [Rigetti Computing](https://www.rigetti.com/).
@@ -30,51 +24,46 @@ PyQuil has a ton of other features, which you can learn more about in the
 [docs](http://pyquil.readthedocs.io/en/latest/). However, you can also keep reading
 below to get started with running your first quantum program!
 
-Quickstart
-----------
+Quickstart with interactive tutorial notebooks
+----------------------------------------------
 
 Without installing anything, you can quickly get started with quantum programming by exploring
 our interactive [Jupyter][jupyter] notebook tutorials and examples. To run them in a preconfigured
 execution environment on [Binder][mybinder], click the "launch binder" badge at the top of the
-README or the link [here][binder]! If you'd like to add your own tutorial, or update an existing
-one, please make a pull request to the [rigetti/forest-tutorials][forest-tutorials] repository
-directly. If you'd rather set everything up locally, or are interested in contributing to pyQuil,
-continue onto the next section for instructions on installing pyQuil and the Forest SDK.
+README or the link [here][binder]! To learn more about the tutorials and how you can add your own,
+visit the [rigetti/forest-tutorials][forest-tutorials] repository. If you'd rather set everything
+up locally, or are interested in contributing to pyQuil, continue onto the next section for
+instructions on installing pyQuil and the Forest SDK.
 
-Installation
-------------
+Installing pyQuil and the Forest SDK
+------------------------------------
 
-**Please Note: PyQuil, along with quilc, the QVM, and other libraries, make up what
-is called the Forest SDK. To make full use of pyQuil's functionality, you will need
-to additionally have installed [quilc](https://github.com/rigetti/quilc) and the
-[QVM](https://github.com/rigetti/qvm). This can be done by following their respective
-READMEs, or by downloading them as binaries from [here](https://rigetti.com/forest).**
-
-PyQuil can be installed using `conda`, `pip`, or directly from source.
-
-To install pyQuil as a `conda` package from the conda-forge channel (recommended), do the following:
-
-```bash
-conda install -c conda-forge pyquil
-```
+[![pypi][pypi-badge]][pypi-repo]
+[![conda-forge][conda-forge-badge]][conda-forge-badge]
+[![conda-rigetti][conda-rigetti-badge]][conda-rigetti-repo]
 
-To instead install pyQuil as a PyPI package, do the following:
+PyQuil can be installed using `conda`, `pip`, or from source. To install it from PyPI (via `pip`),
+do the following:
 
 ```bash
 pip install pyquil
 ```
 
-Finally, if you would prefer to install pyQuil directly from source, do the following
-from within the repository after cloning it:
+To instead install pyQuil from source, do the following from within the repository after cloning it:
 
 ```bash
 pip install -e .
 ```
 
 If you choose to use `pip`, we highly recommend installing pyQuil within a virtual environment.
 
-Getting Started
----------------
+PyQuil, along with quilc, the QVM, and other libraries, make up what is called the Forest
+SDK. To make full use of pyQuil, you will need to additionally have installed
+[quilc](https://github.com/rigetti/quilc) and the [QVM](https://github.com/rigetti/qvm).
+For more information, check out the docs!
+
+Running your first quantum program
+----------------------------------
 
 In just a few lines, we can use pyQuil with the Forest SDK to simulate a Bell state!
 
@@ -111,14 +100,18 @@ the statistics of which are consistent with a two-qubit entangled state.
  [0, 0]]
 ```
 
-Joining the Forest Community
+Using the Forest SDK, you can simulate the operation of a real quantum processor (QPU). If you
+would like to run on the real QPUs in our lab in Berkeley, you can sign up for an account
+on [Quantum Cloud Services](https://www.rigetti.com/qcs) (QCS)!
+
+Joining the Forest community
 ----------------------------
 
-If you'd like to get involved with pyQuil and Forest, joining the [Rigetti Forest Slack
-Workspace][slack_invite]
-is a great place to start! You can do so by clicking the invite link in the previous sentence,
-or in the badge at the top of this README. The Slack Workspace is a great place to ask general
-questions, join high-level design discussions, and hear about updates to pyQuil and the Forest SDK.
+If you'd like to get involved with pyQuil and Forest, joining the
+[Rigetti Forest Slack Workspace][slack-invite] is a great place to start! You can do so by
+clicking the invite link in the previous sentence, or in the badge at the top of this README.
+The Slack Workspace is a great place to ask general questions, join high-level design discussions,
+and hear about updates to pyQuil and the Forest SDK.
 
 To go a step further and start contributing to the development of pyQuil, good first steps are
 [reporting a bug][bug], [requesting a feature][feature], or picking up one of the issues with the
@@ -134,45 +127,78 @@ a detailed list of all announcements, improvements, changes, and bugfixes. The
 information, but with links to the pull request for each change and its corresponding author.
 Thanks for contributing to pyQuil! 🙂
 
-[bug]: https://github.com/rigetti/pyquil/issues/new?assignees=&labels=bug+%3Abug%3A&template=BUG_REPORT.md&title=
-[feature]: https://github.com/rigetti/pyquil/issues/new?assignees=&labels=enhancement+%3Asparkles%3A&template=FEATURE_REQUEST.md&title=
-[first]: https://github.com/rigetti/pyquil/labels/good%20first%20issue%20%3Ababy%3A
-[help]: https://github.com/rigetti/pyquil/labels/help%20wanted%20%3Awave%3A
-[fork]: https://github.com/rigetti/pyquil/fork
-[pr]: https://github.com/rigetti/pyquil/compare
-[slack_invite]: https://join.slack.com/t/rigetti-forest/shared_invite/enQtNTUyNTE1ODg3MzE2LWQwNzBlMjZlMmNlN2M5MzQyZDlmOGViODQ5ODI0NWMwNmYzODY4YTc2ZjdjOTNmNzhiYTk2YjVhNTE2NTRkODY
-
-Running on the QPU
-------------------
-
-Using the Forest SDK, you can simulate the operation of a real quantum processor. If you
-would like to run on the real QPUs in our lab in Berkeley, you can sign up for an account
-on [Quantum Cloud Services](https://www.rigetti.com/qcs)!
+Citing pyQuil, Forest, and Quantum Cloud Services
+-------------------------------------------------
 
-Citing pyQuil and Forest
-------------------------
+[![zenodo][zenodo-badge]][zenodo-doi]
 
-If you use pyQuil, Grove, or other parts of the Rigetti Forest stack in your research,
-please cite it as follows:
+If you use pyQuil, Grove, or other parts of the Forest SDK in your research, please cite
+the [Quil specification][quil-paper] using the following BibTeX snippet:
 
-BibTeX:
-```
-@misc{1608.03355,
-  title={A Practical Quantum Instruction Set Architecture},
-  author={Smith, Robert S and Curtis, Michael J and Zeng, William J},
-  journal={arXiv preprint arXiv:1608.03355},
-  year={2016}
+```bibtex
+@misc{smith2016practical,
+    title={A Practical Quantum Instruction Set Architecture},
+    author={Robert S. Smith and Michael J. Curtis and William J. Zeng},
+    year={2016},
+    eprint={1608.03355},
+    archivePrefix={arXiv},
+    primaryClass={quant-ph}
 }
 ```
 
-Text:
-```
-R. Smith, M. J. Curtis and W. J. Zeng, "A Practical Quantum Instruction Set Architecture," (2016), 
-  arXiv:1608.03355 [quant-ph], https://arxiv.org/abs/1608.03355
+Additionally, if your research involves taking data on Rigetti quantum processors (QPUs) via
+the Quantum Cloud Services (QCS) platform, please reference the [QCS paper][qcs-paper] using the
+following BibTeX snippet:
+
+```bibtex
+@misc{karalekas2020quantumclassical,
+    title={A quantum-classical cloud platform optimized for variational hybrid algorithms},
+    author={Peter J. Karalekas and Nikolas A. Tezak and Eric C. Peterson
+            and Colm A. Ryan and Marcus P. da Silva and Robert S. Smith},
+    year={2020},
+    eprint={2001.04449},
+    archivePrefix={arXiv},
+    primaryClass={quant-ph}
+}
 ```
 
 License
 -------
 
 PyQuil is licensed under the
 [Apache License 2.0](https://github.com/rigetti/pyQuil/blob/master/LICENSE).
+
+[binder]: https://mybinder.org/v2/gh/rigetti/forest-tutorials/master?urlpath=lab/tree/Welcome.ipynb
+[conda-forge-badge]: https://img.shields.io/conda/vn/conda-forge/pyquil.svg
+[conda-forge-repo]: https://anaconda.org/conda-forge/pyquil
+[conda-rigetti-badge]: https://img.shields.io/conda/vn/rigetti/pyquil?label=conda-rigetti
+[conda-rigetti-repo]: https://anaconda.org/rigetti/pyquil
+[coverage-badge]: https://coveralls.io/repos/github/rigetti/pyquil/badge.svg?branch=more-badges
+[coverage-repo]: https://coveralls.io/github/rigetti/pyquil?branch=more-badges
+[docker-badge]: https://img.shields.io/docker/pulls/rigetti/forest
+[docker-repo]: https://hub.docker.com/r/rigetti/forest
+[docs-badge]: https://readthedocs.org/projects/pyquil/badge/?version=latest
+[docs-repo]: http://pyquil.readthedocs.io/en/latest/?badge=latest
+[forest-tutorials]: https://github.com/rigetti/forest-tutorials
+[gitlab-badge]: https://img.shields.io/gitlab/pipeline/rigetti/pyquil
+[gitlab-repo]: https://gitlab.com/rigetti/forest/pyquil
+[jupyter]: https://jupyter.org/
+[mybinder]: https://mybinder.org
+[pepy-badge]: https://pepy.tech/badge/pyquil
+[pepy-repo]: https://pepy.tech/project/pyquil
+[pypi-badge]: https://img.shields.io/pypi/v/pyquil.svg
+[pypi-repo]: https://pypi.org/project/pyquil/
+[slack-badge]: https://img.shields.io/badge/slack-rigetti--forest-812f82.svg?
+[zenodo-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.3604432.svg
+[zenodo-doi]: https://doi.org/10.5281/zenodo.3604432
+
+[qcs-paper]: https://arxiv.org/abs/2001.04449
+[quil-paper]: https://arxiv.org/abs/1608.03355
+
+[bug]: https://github.com/rigetti/pyquil/issues/new?assignees=&labels=bug+%3Abug%3A&template=BUG_REPORT.md&title=
+[feature]: https://github.com/rigetti/pyquil/issues/new?assignees=&labels=enhancement+%3Asparkles%3A&template=FEATURE_REQUEST.md&title=
+[first]: https://github.com/rigetti/pyquil/labels/good%20first%20issue%20%3Ababy%3A
+[help]: https://github.com/rigetti/pyquil/labels/help%20wanted%20%3Awave%3A
+[fork]: https://github.com/rigetti/pyquil/fork
+[pr]: https://github.com/rigetti/pyquil/compare
+[slack-invite]: https://join.slack.com/t/rigetti-forest/shared_invite/enQtNTUyNTE1ODg3MzE2LWQwNzBlMjZlMmNlN2M5MzQyZDlmOGViODQ5ODI0NWMwNmYzODY4YTc2ZjdjOTNmNzhiYTk2YjVhNTE2NTRkODY

requirements.txt

@@ -12,6 +12,7 @@ ipython
 
 # test deps
 black
+coveralls
 flake8
 flake8-bugbear
 mypy==0.740