Update and refresh cirq-* module README files #6900
Conversation
This updates all the cirq-* module files to fix some broken image links, spiff up the layout and formatting, and add some additional links here and there.
rstcheck complains about it.
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #6900 +/- ##
=======================================
Coverage 97.87% 97.87%
=======================================
Files 1084 1084
Lines 94420 94495 +75
=======================================
+ Hits 92409 92484 +75
Misses 2011 2011 ☔ View full report in Codecov by Sentry. |
mhucka
requested review from
vtomole,
a team,
HGSilveri,
ma5x,
pschindler,
dabacon,
ColemanCollins,
nakardo,
gmauricio,
wcourtney and
verult
as code owners
cirq-google/README.rst
Outdated
| Access to Google Hardware is currently restricted to those in an approved group. In order to do this, you will need to apply for access, typically in partnership with a Google sponsor. | ||
| This Python module is |cirq-google|, which provides everything you'll need to | ||
| run |cirq|_ quantum algorithms on the Google `Quantum Computing Service | ||
| <https://quantumai.google/cirq/google/concepts>`__. It also contains |
There was a problem hiding this comment.
Should we clarify here (and maybe in the other vendor packages) that this is only open to authorized partners? (i.e. it's not everything you need)
There was a problem hiding this comment.
What do you think of the revised version?
There was a boxed paragraph two paragraphs below the paragraph where the text above appears; I moved that box right under the first paragraph so that the note is more obvious. Please let me know what you think.
There was a problem hiding this comment.
This looks good to me. What do you think of adjusting text for the other vendor modules as well? We could do a much more simpler change, such as changing "this module contains everything you need for ..." to "this module contains all the code you need for... See for more information on getting a license key for this service"
| * To install the latest pre-release version of |cirq-aqt|, use ``pip install | ||
| cirq-aqt~=1.0.dev``. (The ``~=`` has a special meaning to ``pip`` of | ||
| selecting the latest version compatible with the ``1.*`` and ``dev`` in the | ||
| name. Despite appearances, this will not install an old version 1.0 release!) |
There was a problem hiding this comment.
Minor point - let us have installation command on one line so it is easier to copy/paste from GitHub-rendered README. The current text pastes as an invalid two-line shell command.
Also please check for similar line-wrapped commands in other README-s.
(Format only, no change in the text)
| * To install the latest pre-release version of |cirq-aqt|, use ``pip install | |
| cirq-aqt~=1.0.dev``. (The ``~=`` has a special meaning to ``pip`` of | |
| selecting the latest version compatible with the ``1.*`` and ``dev`` in the | |
| name. Despite appearances, this will not install an old version 1.0 release!) | |
| * To install the latest pre-release version of |cirq-aqt|, use | |
| ``pip install cirq-aqt~=1.0.dev`` | |
| (The ``~=`` has a special meaning to ``pip`` of selecting the latest version | |
| compatible with the ``1.*`` and ``dev`` in the name. Despite appearances, | |
| this will not install an old version 1.0 release!) |
There was a problem hiding this comment.
Yes, that's a good idea. (I think I only did it that way because the originals were as well. But it's better the way you suggest.
| .. |cirq-aqt| replace:: ``cirq-aqt`` | ||
| .. |cirq-core| replace:: ``cirq-core`` |
There was a problem hiding this comment.
Nit - do we need these substitutions if they are nearly the same as their expansion?
There was a problem hiding this comment.
It is easier to achieve consistent formatting throughout a document when substitutions are defined. My experience is that when foo is used all over, sooner or later it's forgotten in some places, and the document starts to look sloppy. Also, it makes it easier to change or add formatting (such as hyperlinks). It's the same principle as defining macros for common terms in LaTeX. (I'm sure this is all familiar and I'm just overexplaining …)
There was a problem hiding this comment.
That said, I'm not strongly bothered by getting rid of the substitutions and just doing foo. These are short documents, after all.
| .. |cirq-aqt| replace:: ``cirq-aqt`` | ||
| .. |cirq-core| replace:: ``cirq-core`` | ||
|
|
||
| .. class:: centered |
There was a problem hiding this comment.
With apologies for bike-shedding - could we perhaps just leave the left-aligned default?
It would make the text look the same on GitHub and PyPi and would be perhaps more consistent with the logo-on-the-left layout at https://quantumai.google/cirq.
There was a problem hiding this comment.
With respect, I don't think there's any need to match that page.
| Installation | ||
| ------------ | ||
|
|
||
| |cirq-web| is currently in development, and therefore is only available in |
There was a problem hiding this comment.
cirq-web is actually available as a "stable" package at https://pypi.org/project/cirq-web/ and it installs together with the cirq metapackage. The installation info should be similar as for the other sub-packages.
There was a problem hiding this comment.
Oh, woops, that text needs to be corrected!
|
|
||
|
|
There was a problem hiding this comment.
maybe remove these blanks?
There was a problem hiding this comment.
I was using 2 blank lines before section headings, just as a convention. It's not uncommon if you all prefer single blank lines, that's okay with me.
This updates all the cirq-* module files to fix some broken image links, spiff up the layout and formatting, and add some additional links here and there.
As before, these remain purposefully short and fairly minimal because these are add-only modules to the main
cirqdistribution. The main package README will be much fuller.Due to differences in reStructuredText support between GitHub and PyPI, some desirable attractive formatting cannot be achieved without using raw HTML, which PyPI does not support. I decided to focus on PyPI rather than GitHub for these README files; the rationale is that these modules are separate packages on PyPI and thus have their own landing pages there, which makes them more visible than on GitHub where they are buried in subdirectories of the overall Cirq repo. Consequently, these files look slightly better on PyPI than on GitHub.
Here are a couple of examples of what the result looks like on PyPI: