From a62ed8be6643bfa0a8f6eef84d11bc5d2dde5dfd Mon Sep 17 00:00:00 2001 From: Balint Pato Date: Thu, 3 Sep 2020 10:32:58 -0700 Subject: [PATCH] removing readthedocs.io references (#3294) We should not refer to readthedocs.io from our docs for content, unless it's absolutely necessary. This removes the last readthedocs.io references. --- dev_tools/conf/pip-list-dev-tools.txt | 2 +- docs/dev/development.md | 14 +++++++------- docs/dev/nomenclature.md | 4 ++-- docs/devices.md | 2 +- docs/install.md | 12 ++++++------ docs/tutorials/examples.md | 10 +++++----- docs/tutorials/variational_algorithm.ipynb | 2 +- rtd_docs/conf.py | 4 +++- 8 files changed, 26 insertions(+), 24 deletions(-) diff --git a/dev_tools/conf/pip-list-dev-tools.txt b/dev_tools/conf/pip-list-dev-tools.txt index 21d750735af..006ec88dcec 100644 --- a/dev_tools/conf/pip-list-dev-tools.txt +++ b/dev_tools/conf/pip-list-dev-tools.txt @@ -22,7 +22,7 @@ qiskit~=0.13.0 # For generating documentation. pypandoc -recommonmark >= 0.4.0 +myst-parser Sphinx~=3.2.0 sphinx_rtd_theme sphinx-markdown-tables diff --git a/docs/dev/development.md b/docs/dev/development.md index 395c7858f64..79dbd9dda7e 100644 --- a/docs/dev/development.md +++ b/docs/dev/development.md @@ -1,10 +1,10 @@ -## Development +# Development This document is a summary of how to do various tasks one runs into as a developer of Cirq. Note that all commands assume a Debian environment, and all commands (except the initial repository cloning command) assume your current working directory is the cirq repo root. -### Cloning the repository +## Cloning the repository The simplest way to get a local copy of cirq that you can edit is by cloning Cirq's github repository: @@ -24,7 +24,7 @@ If you want to contribute changes to Cirq, you will instead want to fork the rep -### Forking the repository +## Forking the repository 1. Fork the Cirq repo (Fork button in upper right corner of [repo page](https://github.com/quantumlib/Cirq)). @@ -62,7 +62,7 @@ Most importantly you should see ```upstream/master``` listed. At this point your local git master should be synced with the master from the main cirq repo. -### Setting up an environment +## Setting up an environment 0. First clone the repository, if you have not already done so. See the previous section for instructions. @@ -112,7 +112,7 @@ See the previous section for instructions. add2virtualenv ./ ``` -### Protocol buffers +## Protocol buffers [Protocol buffers](https://developers.google.com/protocol-buffers) are used in Cirq for converting circuits, gates, and other objects into a standard form that can be written and read by other programs. Cirq's protobufs live at [cirq/api/google](https://github.com/quantumlib/Cirq/tree/master/cirq/api/google) and may need to be changed or extended from time to time. @@ -124,7 +124,7 @@ Additionally, for workflows that use bazel (relevant for C/C++ code depending on These rules live in the BUILD files [here](https://github.com/quantumlib/Cirq/tree/master/cirq/api/google/v1) and [here](https://github.com/quantumlib/Cirq/tree/master/cirq/api/google/v2). Downstream projects should load Cirq as an [external dependency](https://docs.bazel.build/versions/master/external.html), allowing rules from those BUILD files to be used directly. -### Continuous integration and local testing +## Continuous integration and local testing There are a few options for running continuous integration checks, varying from easy and fast to slow and reliable. @@ -276,7 +276,7 @@ dev_tools/docs/build-rtd-docs.sh The HTML output will go into the `dev_tools/rtd_docs/sphinx/_build` directory. -### Producing a pypi package +## Producing a pypi package 1. Do a dry run with test pypi. diff --git a/docs/dev/nomenclature.md b/docs/dev/nomenclature.md index a33b7393c29..ffdab6b7944 100644 --- a/docs/dev/nomenclature.md +++ b/docs/dev/nomenclature.md @@ -1,4 +1,4 @@ -## Nomenclature +# Nomenclature This page describes naming rules and conventions that exist throughout Cirq. These rules are important in order to maintain a consistent interface that is @@ -8,7 +8,7 @@ users and developers. Please try to use these terms when writing code. If you have suggestions for improvements or changes, please create a PR to modify this list or open an issue. -### Quantum computing terms +## Quantum computing terms Use `state_vector` to describe a pure state that is passed in as a numpy array, numpy tensor, or list of amplitudes. **Do not** use `wavefunction`, diff --git a/docs/devices.md b/docs/devices.md index ba4a61c4752..d530ea81343 100644 --- a/docs/devices.md +++ b/docs/devices.md @@ -1,4 +1,4 @@ -### Devices +# Devices The ``Device`` class is an abstract class which encapsulates constraints (or lack thereof) that come when running a circuit on actual hardware. diff --git a/docs/install.md b/docs/install.md index 570869e025f..71d0b398032 100644 --- a/docs/install.md +++ b/docs/install.md @@ -1,4 +1,4 @@ -## Installing Cirq +# Installing Cirq Choose your operating system: @@ -11,14 +11,14 @@ If you want to create a development environment, see the [development page](dev/ --- -### Alpha Disclaimer +## Alpha Disclaimer **Cirq is currently in alpha.** We may change or remove parts of Cirq's API when making new releases. To be informed of deprecations and breaking changes, subscribe to the [cirq-announce google group mailing list](https://groups.google.com/forum/#!forum/cirq-announce). -### Installing on Linux +## Installing on Linux 0. Make sure you have python 3.6.0 or greater. @@ -61,7 +61,7 @@ To be informed of deprecations and breaking changes, subscribe to the ``` -### Installing on Mac OS X +## Installing on Mac OS X 0. Make sure you have python 3.5 or greater. @@ -102,7 +102,7 @@ To be informed of deprecations and breaking changes, subscribe to the ``` -### Installing on Windows +## Installing on Windows 0. If you are using the [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/about), use the [Linux install instructions](#installing-on-linux) instead of these instructions. @@ -135,7 +135,7 @@ To be informed of deprecations and breaking changes, subscribe to the ``` -### Installing on Docker +## Installing on Docker This will use a Docker image that will isolate Cirq's installation from the rest of the system. diff --git a/docs/tutorials/examples.md b/docs/tutorials/examples.md index ab3dfc3fe9c..4506ee7a971 100644 --- a/docs/tutorials/examples.md +++ b/docs/tutorials/examples.md @@ -100,22 +100,22 @@ Quantum circuit to prepare the BCS ground states for superconductors/superfluids ## Advanced Tutorials -* [Variational Algorithm](https://cirq.readthedocs.io/en/latest/tutorials/variational_algorithm.html) +* [Variational Algorithm](./variational_algorithm.ipynb) Case study demonstrating construction of an ansatz for a two-dimensional Ising model and how to simulate and optimize it. -* [QAOA](https://cirq.readthedocs.io/en/latest/tutorials/QAOA_Demo.html) +* [QAOA](./QAOA_Demo.ipynb) Demonstration of optimizing cost of a max-cut problem using quantum approximation optimization algorithm (QAOA) -* [Hidden Linear Function](https://cirq.readthedocs.io/en/latest/tutorials/hidden_linear_function.html) +* [Hidden Linear Function](./hidden_linear_function.ipynb) Demonstration of a problem similar to Bernstein-Vazirani that uses a hidden function rather than using an Oracle. -* [Quantum Walk](https://cirq.readthedocs.io/en/latest/tutorials/Quantum_Walk.html) +* [Quantum Walk](./Quantum_Walk.ipynb) Demonstration of both classical and quantum random walks that shows their similarities and differences. -* [Rabi Oscillations](https://cirq.readthedocs.io/en/latest/tutorials/Rabi_Demo.html) +* [Rabi Oscillations](./Rabi_Demo.ipynb) Example of using sweeps and symbols to show rotation of a qubit by different angles. diff --git a/docs/tutorials/variational_algorithm.ipynb b/docs/tutorials/variational_algorithm.ipynb index d6088238fdc..db1fb36b532 100644 --- a/docs/tutorials/variational_algorithm.ipynb +++ b/docs/tutorials/variational_algorithm.ipynb @@ -42,7 +42,7 @@ "\n", "In this tutorial, we will create a [quantum variational algorithm](https://arxiv.org/abs/1304.3061) using cirq and show how it can optimize a simple Ising model.\n", "\n", - "To begin, please follow the instructions for [installing Cirq](https://cirq.readthedocs.io/en/latest/install.html)." + "To begin, please follow the instructions for [installing Cirq](../install.md)." ] }, { diff --git a/rtd_docs/conf.py b/rtd_docs/conf.py index 8e2bd829524..7a20d449b4b 100644 --- a/rtd_docs/conf.py +++ b/rtd_docs/conf.py @@ -153,7 +153,7 @@ def autodoc_process(app, what: str, name: str, obj: Any, options, # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'recommonmark', + 'myst_parser', 'nbsphinx', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', @@ -272,3 +272,5 @@ def autodoc_process(app, what: str, name: str, obj: Any, options, # to resolve name clashes between the generated files autosummary_filename_map = {"cirq.QFT": "cirq.QFT_deprecated"} + +myst_update_mathjax = False \ No newline at end of file