Overhaul top-level README.rst file #6903

mhucka · 2024-12-31T20:52:06Z

This is a major overhaul of the main Cirq README.rst file. Much of the content is rewritten, and there are numerous additions and enhancements all over. The changes include but are not limited to:

Updates and corrections
Addition of new sections
Centering and resizing the logo for a more professional look
Addition of GitHub badges for extra "pizzazz"
Addition of a table of contents
Addition of pointers to other Quantumlib software
Improvements to info about how to cite Cirq

Note: this new README.rst depends on PRs #6902 and #6901 to be merged into main before this file will fully work.

Below is a screenshot of what the result will look like. (Note: updated on 2025-01-09.)

Here is a PDF version of the same: New Cirq README

This is a major overhaul of the main Cirq README.rst file. Much of the content is rewritten, and there are numerous additions and enhancements all over. The changes include but are not limited to: - Updates and corrections - Addition of new sections - Centering and resizing the logo for a more professional look - Addition of GitHub badges for extra "pizzazz" - Addition of a table of contents - Addition of pointers to other Quantumlib software - Improvements to info about how to cite Cirq

codecov · 2024-12-31T21:03:38Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.87%. Comparing base (ecf9ed7) to head (66f02f1).
Report is 16 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6903   +/-   ##
=======================================
  Coverage   97.86%   97.87%           
=======================================
  Files        1084     1084           
  Lines       94315    94408   +93     
=======================================
+ Hits        92301    92398   +97     
+ Misses       2014     2010    -4

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

@dstrain115

Per discussion with @dstrain115 today, we're removing this image for the time being. We need to check with relevant QAI leadership about what images we are allowed to use on non-Google-hosted sites like GitHub.

@Dstrain

@Dstrain had reservations about the way Stim was initially described. The new version puts Stim in its own category. I also shuffled the rows a little bit to try to put related things together.

mhucka · 2025-01-09T17:10:32Z

Updated the README to account for changes requested by @dstrain115: removing the image of the quantum computer for now, and changing the description of Stim in the table in the Integrations section.

dstrain115 · 2025-01-14T03:15:15Z

README.rst

+  meeting of contributors to discuss everything from issues to ongoing
+  efforts, as well as to ask questions. Join the `cirq-dev Google Group
+  <https://groups.google.com/forum/#!forum/cirq-dev>`__ to get an automatic
+  meeting invitation.


Maybe a quick note that this is for group membership and we don't typically post messages there, in case people see no one has posted in forever.

Oh yes, that's a good point. I'll add a note.

Alright, I reworded this a little bit – how is it now?

pavoljuhas

Please see inline. I feel we should drop the conditional blocks also let us have a prominent link to the Cirq homepage.

pavoljuhas · 2025-01-16T09:20:51Z

README.rst

+.. |license| image:: https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square
+   :alt: Licensed under the Apache 2.0 license
+   :target: https://github.com/quantumlib/Cirq/blob/main/LICENSE


I feel some of the new badges duplicate existing content on our top GitHub page or are not very informative. Perhaps we could limit ourselves to fewer more essential badges.

Please consider removing

license badge - the License link is already at the top of the README frame in project top page

Google Colab - not sure if it helps a novice user, advanced users would likely already know about Colabs and Jupyter notebooks. There are colab links later on in the tutorial section where they are more helpful.

Contributors badge - the link is in the Insights tab of the GH page, which more casual GH users would likely know about. We could add it as a hyperlink to the Community section instead, e.g., "Cirq has benefited from work of over 200 open-source contributors ..."

GH stars badge - the same info is already at the top of the project page

pavoljuhas · 2025-01-16T09:30:15Z

README.rst

+`Features <#features>`__ –
+`Installation <#installation>`__ –
+`Quick Start <#quick-start-hello-qubit-example>`__ –
+`Documentation <#cirq-documentation>`__ –
+`Integrations <#integrations>`__ –
+`Community <#community>`__ –
+`Citing Cirq <#citing-cirq>`__ –
+`Contact <#contact>`__


Do we really need TOC? The document does not feel that long for it to be essential.

My main concern is that the anchor links will likely break should section titles change in the future or become out-of-sync with the actual sections.
Perhaps we can save on overhead of manually maintaining the TOC here.

pavoljuhas · 2025-01-16T15:57:08Z

README.rst

+.. ▶︎─── start github-only ───
+.. PyPI supports RST's ".. class::", but GitHub does not. PyPI respects
+.. ":align: center" for images, but GitHub does not. The only way to center
+.. text or images in GitHub is to use raw HTML -- which PyPI rejects (!!!).
+.. To satisfy both, this file contains fences around code that is removed
+.. when creating distributions for PyPI.
+
+.. raw:: html
+
+   <div align="center">
+.. ▶︎─── end github-only ───


Please let us not add these optional blocks. It would impose a lot of overhead on future editors to keep them in sync and their HTML tags appropriately paired. I feel that centered format is just not worth the effort here.

~~Personally, the default left alignment looks fine to me. If we really must have centering it is OK to center on PyPI only and accept left alignment on GitHub.~~

Update - Let us apply centering in a follow-up PR together with a conversion of rst to markdown.

pavoljuhas · 2025-01-16T16:03:04Z

README.rst

+   :alt: Download MARCXML bibliography record for latest Cirq release
+   :target: https://zenodo.org/records/8161252/export/marcxml
+
+.. |csl| image:: https://img.shields.io/badge/Download%20record-eeeeee.svg?style=flat-square&label=CSL&labelColor=2d98e0&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAUCAMAAADbT899AAAACXBIWXMAAAnXAAAJ1wGxbhe3AAABGlBMVEUtmOBZreZhsuhSquVNp+RfsOcsmOD///92vOs3neHx+P2n1PLY7PrS6fmi0vE7nuJ8v+z+//9Tq+VJpuT8/v+Fw+3t9/2r1vPH4/fd7vovmeCf0PH0+v5uuOlesOfV6/nO5/ik0vLy+f41nOFbr+fL5vhVq+Y6nuLI5Pd6vutotelntOg/oOL2+/6YzfDb7vrQ6Pim1PLw+P04neHK5fcumOCUy+/4/P5CouNst+k7n+Lz+f6e0PFQqeX9/v9+wOwzm+Ht9v2w2PPB4fbg8PuPyO/7/f9HpeSt1/NLp+SDwu3p9fy33PV5vetVrOZSq+av2POczvA+oOJ1u+tFpOOMx+7q9fyy2fS+3/bi8fsxmuCWzPBBouNaruaHgOQWAAAAXnRSTlP////////+///////////////////////////////////////////////////////////////////////////////////////////////+/v//////////////////3JzDywAAAQRJREFUeJyNkddWwkAURS9VgyBFDYIFdewNlAQrVcVewQr+/2+Yc3gylwfuy5619pk5mYnIKBMIehOSMBD5r6L0Y5hxKwZMDAnEIRIyCcSSuiAFkc5MTYMz2ls2RFZmgVzeZ72KOYj55AI/ZNG/3QsUIJZkGVgxq2uY9Y1NYIuBbW7d2d0D9qUIlOQAOCzzFAfrolsBjo6DzJ+cngHnvGa1hnW90QRacgFc5q+A9jXf4QbrpuF1a9VbXveucQ88sGNQX3FZ70iW9eaRXU9D/gwDtjUIPGufSUOkDN/vJaoDCYi4vPL93rTv8ORAtw28a28+ID7lC/j+EVUR6mH6FvErOqDmD0UfH1PhwykNAAAAAElFTkSuQmCC


Do we truly need to include the base64 encoded PNG image in the link?
A shorter link
https://img.shields.io/badge/Download%20record-eeeeee.svg?style=flat-square&labelColor=2d98e0
appears to work as well.

pavoljuhas · 2025-01-16T16:05:44Z

README.rst

@@ -62,65 +176,231 @@ A simple example to get you up and running:
  print("Results:")
  print(result)

-Example output:
+You should see the following output printed by Python:


Nit - the result m is random and will likely differ in user's run

Suggested change

You should see the following output printed by Python:

You should see a similar output printed by Python:

pavoljuhas · 2025-01-16T16:35:38Z

README.rst


-Cirq is uploaded to Zenodo automatically. Click on the badge below to see all the citation formats for all versions.
+Tutorials


The original README had a "Tutorials" link pointing to https://quantumai.google/cirq/build which is absent in the new version. I feel that page is very useful for new users, because the tutorials there are categorized by subject and link to nicely rendered notebooks, no need to figure and run colabs at all.

Can we add a leading bullet point for these? For example (feel free to reword as you see fit)

Tutorials at the Cirq homepage, for example, circuit building and circuit simulation tutorials under the Build and Simulate tabs respectively. Please see other tabs for more tutorials.

pavoljuhas · 2025-01-16T16:39:50Z

README.rst


-If you have feature requests or you found a bug, please `file them on GitHub <https://github.com/quantumlib/Cirq/issues/new/choose>`__.
+Cirq Documentation
+------------------


The primary documentation source is the Cirq homepage (which seems to be missing).

Can we add it prominently as the first link in the Documentation?

CirqBot added the size: L 250< lines changed <1000 label Dec 31, 2024

mhucka added the area/docs label Dec 31, 2024

mhucka self-assigned this Dec 31, 2024

mhucka marked this pull request as ready for review December 31, 2024 21:11

mhucka requested review from vtomole and a team as code owners December 31, 2024 21:11

mhucka requested a review from MichaelBroughton December 31, 2024 21:11

mhucka mentioned this pull request Jan 2, 2025

Convert reStructuredText (.rst) files to Markdown (.md) format #6805

Closed

mhucka and others added 4 commits January 7, 2025 08:46

Merge branch 'main' into mhucka-overhaul-top-readme

3598516

Merge branch 'quantumlib:main' into mhucka-overhaul-top-readme

96ad07e

Removing image of quantum computer for now

cb9a84d

Per discussion with @dstrain115 today, we're removing this image for the time being. We need to check with relevant QAI leadership about what images we are allowed to use on non-Google-hosted sites like GitHub.

Edit the table of related software

3da2046

@Dstrain had reservations about the way Stim was initially described. The new version puts Stim in its own category. I also shuffled the rows a little bit to try to put related things together.

mhucka requested a review from pavoljuhas January 9, 2025 17:50

dstrain115 approved these changes Jan 14, 2025

View reviewed changes

Try to clarify what cirq-dev is for

66f02f1

pavoljuhas mentioned this pull request Jan 16, 2025

Add support for conditional blocks in README.rst #6901

Open

pavoljuhas requested changes Jan 16, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overhaul top-level README.rst file #6903

Overhaul top-level README.rst file #6903

mhucka commented Dec 31, 2024 •

edited

Loading

codecov bot commented Dec 31, 2024 •

edited

Loading

mhucka commented Jan 9, 2025

dstrain115 Jan 14, 2025

mhucka Jan 14, 2025

mhucka Jan 14, 2025

pavoljuhas left a comment

pavoljuhas Jan 16, 2025 •

edited

Loading

pavoljuhas Jan 16, 2025

pavoljuhas Jan 16, 2025 •

edited

Loading

pavoljuhas Jan 16, 2025

pavoljuhas Jan 16, 2025

pavoljuhas Jan 16, 2025 •

edited

Loading

pavoljuhas Jan 16, 2025

	You should see the following output printed by Python:
	You should see a similar output printed by Python:


		Cirq is uploaded to Zenodo automatically. Click on the badge below to see all the citation formats for all versions.
		Tutorials

Overhaul top-level README.rst file #6903

Are you sure you want to change the base?

Overhaul top-level README.rst file #6903

Conversation

mhucka commented Dec 31, 2024 • edited Loading

codecov bot commented Dec 31, 2024 • edited Loading

Codecov Report

mhucka commented Jan 9, 2025

dstrain115 Jan 14, 2025

Choose a reason for hiding this comment

mhucka Jan 14, 2025

Choose a reason for hiding this comment

mhucka Jan 14, 2025

Choose a reason for hiding this comment

pavoljuhas left a comment

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

pavoljuhas Jan 16, 2025

Choose a reason for hiding this comment

mhucka commented Dec 31, 2024 •

edited

Loading

codecov bot commented Dec 31, 2024 •

edited

Loading

pavoljuhas Jan 16, 2025 •

edited

Loading

pavoljuhas Jan 16, 2025 •

edited

Loading

pavoljuhas Jan 16, 2025 •

edited

Loading