quantumlib
Docs|Tutorials: Inconsistent reference style
Description of the issue In the Cirq tutorials there is a variety of reference styles. Making these consistent would probably not only make a slightly better impression to the reader, but also would help them to identify references faster; in particularly if the references were placed consistently at the end of each file/page.
Examples of the current reference style variety:
- Journal style reference with Author, Title, Journal, DOI (Deutsch-Jozsa algorithm) https://quantumai.google/cirq/tutorials/educators/intro
- Link on author name https://quantumai.google/cirq/tutorials/educators/qaoa_ising
- Link on arXiv reference https://github.com/quantumlib/Cirq/blob/master/docs/tutorials/educators/chemistry.ipynb
- Link to journal article, without naming author, title or journal (Quantum teleportation) https://quantumai.google/cirq/tutorials/educators/textbook_algorithms
Suggestion to resolve the issue Use journal-inspired consistent references and put them at the end of each file into a reference block, similar to:
- Numpy Docs: https://numpy.org/doc/stable/reference/generated/numpy.linalg.eigh.html
- Scipy Docs: https://docs.scipy.org/doc/scipy/reference/generated/scipy.sparse.linalg.eigsh.html
- Cirq Docs: https://quantumai.google/reference/python/cirq/ops/ISwapPowGate
Cirq version cirq.master
xref https://github.com/quantumlib/Cirq/issues/5151
Hi @TimoEckstein! Sorry if I miss anything, I tried to locate the doc mentioned in this issue (e.g. qaoa_ising) within the Cirq codebase, but I couldn't find it. Checking the doc index docs/experiments/_index.yaml, there is less than what I saw in the official quantumai.google doc site.
I can still try to work on checking the docs that are available within the codebase, feel free to assign to me!
Hi! I drafted a PR #7577 for this issue, please let me know if you have any thought. :)
NOTE: I checked style guide in #5220 and Google style guide, both mentioned more about how we handle external links in general, but not how the reference style should look like. So for this part, I referred to the Numpy Doc page as @TimoEckstein suggested.