Add tags to tutorials

[purva-thakre]

Description

Fixes #2463

The following are WIP:

• Need to add Basic, Intermediate and Advanced tags.
• Couple of tutorial examples show up as jupyter notebooks. If a tag does not exist, the new tag file does not created if it is first used in the jupyter notebook. Discussed it is fine to not have a pyquil tag during the community call
• Fix a color scheme for frontend, backend, qem technique badges

---

License

• I license this contribution under the terms of the GNU GPL, version 3 and grant Unitary Fund the right to provide additional permissions as described in section 7 of the GNU GPL, version 3.

Before opening the PR, please ensure you have completed the following where appropriate.

• I added unit tests for new code.
• I used type hints in function signatures.
• I used Google-style docstrings for functions.
• I updated the documentation where relevant.
• Added myself / the copyright holder to the AUTHORS file

[purva-thakre]

Most of these added files in _tags are causing a few build warnings. Might need to fix some build errors when dependabot upgrades to 9.0.

RemovedInSphinx90Warning: Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead

https://github.com/unitaryfund/mitiq/actions/runs/10363857000/job/28688193465?pr=2467#step:8:212

[purva-thakre]

This warning appears to be an issue that could be fixed by downgrading Sphinx < 8.0

executablebooks/MyST-NB#619

[purva-thakre]

test failures are instances of #2431

https://github.com/unitaryfund/mitiq/actions/runs/10363857010/job/28688193711?pr=2467#step:6:4486

https://github.com/unitaryfund/mitiq/actions/runs/10363857010/job/28688194019?pr=2467#step:6:4486

[purva-thakre]

We have 2 pyquil tutorials in ipnyb format. If I follow the instructions provided by sphinx-tags, new tags in ipnyb files are not created.

For example, if I have an ipnyb file with tags pyquil and zne, the tag for pyquil is not created in _tags/ as I had not used this tag label before. There were no issues with the zne tag because this file already exists in _tags/. 844df51

https://github.com/unitaryfund/mitiq/actions/runs/10391784801/job/28775505338#step:8:1366

[bdg221]

I know you are working on the functionality, but currently tags are shown on the examples page in the following places:

I think having the tags above the examples could be a useful place for it:

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.71%. Comparing base (4046cf6) to head (d6ac335).
Report is 20 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2467      +/-   ##
==========================================
+ Coverage   98.70%   98.71%   +0.01%     
==========================================
  Files          88       89       +1     
  Lines        4091     4131      +40     
==========================================
+ Hits         4038     4078      +40     
  Misses         53       53              

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

[purva-thakre]

@bdg @cosenal This PR is ready for a review.

Not sure why the RTD build is failing. Will look into this later. You should still be able to verify the changes in a local build.

Force push worked!

---

Screenshot of previous RTD failure.

[bdg221]

@purva-thakre I think the tag implementation is great. My only concern is that a user going to the examples page, will have to take extra steps to use the tags. Is there a way that the links to the tags could be incorporated into the examples page so that they can be accessed without an extra click?

This may just be me nitpicking and if @cosenal and you think the details you provided at the top of the examples page is sufficient, then that's cool with me.

[jordandsullivan]

@bdg221 I agree it would be nice to have the tags at the top of the page, but I think we could do that in a separate issue, unless @purva-thakre thinks it would be easier to just add it to this one.

[purva-thakre]

The tags become a long list on top of the examples. Which is why I chose to move them to a separate page.

There's no way to list the tags horizontally because they are autogenerated as shown below:

mitiq/docs/source/_tags/tagsindex.md

Lines 4 to 29 in 8aad7b3

	```{toctree}
	---
	caption: Tags in the documentation tutorials:
	maxdepth: 1
	---
	advanced (11) <advanced>
	basic (12) <basic>
	bqskit (1) <bqskit>
	braket (3) <braket>
	calibration (1) <calibration>
	cdr (2) <cdr>
	cirq (17) <cirq>
	ddd (3) <ddd>
	intermediate (8) <intermediate>
	ionq (1) <ionq>
	pec (2) <pec>
	pennylane (3) <pennylane>
	qibo (1) <qibo>
	qiskit (11) <qiskit>
	qrack (1) <qrack>
	rem (1) <rem>
	shadows (2) <shadows>
	stim (1) <stim>
	zne (24) <zne>
	```

[bdg221]

Sounds like there isn't an easy way to get the tags to horizontally appear above the examples and it makes more sense to put that in a separate issue.

[bdg221]

Initial implementation of tags looks good.

[purva-thakre]

Sounds like there isn't an easy way to get the tags to horizontally appear above the examples and it makes more sense to put that in a separate issue.

@bdg221 Feel free to create the issue and assign it to yourself, if you are interested.

This would involve requesting a new feature in https://github.com/melissawm/sphinx-tags because the examples in the official documentation are also using a vertical list. I chose to use sphinx-tags due to its ability to auto-generate the tags page.

[cosenal]

Unless there is a specific reason for it (e.g. you manually adjusted some tag definition), I don't see much value in including the _tags folder in the repo. The only benefit I can think of would be build consistency across different environments. However, we don't version control the docs/build folder anyway, so we may as well do the same for _tags.

[cosenal]

@bdg221 Did you mean to click on «Request changes»? It's not clear from your comment.

[purva-thakre]

Unless there is a specific reason for it (e.g. you manually adjusted some tag definition)

@cosenal I had to manually add tagsindex.md to docs/source/examples/tags.md. The latter is then linked on docs/source/examples/examples.md.

[cosenal]

Unless there is a specific reason for it (e.g. you manually adjusted some tag definition)

@cosenal I had to manually add tagsindex.md to docs/source/examples/tags.md. The latter is then linked on docs/source/examples/examples.md.

You can still do that while gitignoring the _tags folder, no?

[bdg221]

@bdg221 Did you mean to click on «Request changes»? It's not clear from your comment.

No, I didn't mean to. I've cleared it now.

[purva-thakre]

You can still do that while gitignoring the _tags folder, no?

@cosenal You're correct.

For some reason, I thought the build would fail if I don't have the autogenerated .md files in the _tags folder.

Although every time we run make html, the tool is going to add the .md files.

[natestemen]

Not sure if this is configurable, but is it possible to make the URL .../tags/... instead of .../_tags/...? It's a vanity thing, but _tags makes me think it's private! 😆

[purva-thakre]

Converting to a draft to look into Nate's comment as well as the issue with make docs adding back the .md files in _tags.

[cosenal]

I actually like the convention of using underscore in front of "build" folders in order to make them recognizable from folders that contain source files 🤷🏻‍♂️

[purva-thakre]

@cosenal Looking through the configuration settings for sphinx-tags, they do not have a setting for not keeping the autogenerated files.

So, even if I deleted the autogenerated files in this PR, someone else running make docs locally will have to make sure to delete these files. We could request this as a feature in the project repo. I know some sphinx tools do have a setting to not keep these files.

[cosenal]

@purva-thakre the mechanism you just described is .gitignore, which I see you have already modified accordingly :)

[cosenal]

LGTM 🏷️

[natestemen]

I actually like the convention of using underscore in front of "build" folders in order to make them recognizable from folders that contain source files 🤷🏻‍♂️

Yeah I generally agree with this as a method to indicate on your local machine what's happening. When that pattern shows its face publicly, however, I find strange. My comment was referring to the URL of the tags on the built documentation. E.g. in the current RTD build it reads

mitiq--2467.org.readthedocs.build/en/2467/_tags/qiskit.html

but it would look more natural IMO to be

mitiq--2467.org.readthedocs.build/en/2467/tags/qiskit.html

This is not a hill I'd like to die on, however. Again, just a vanity thing.

While it's a topic of discussion, however, would tag be more appropriate here than tag?

[purva-thakre]

@purva-thakre the mechanism you just described is .gitignore, which I see you have already modified accordingly :)

Ah, yes. Initially, I had an incorrect path to _tags in gitignore. This is why the .md files were being added locally whenever I ran make docs. Fixed in 8f8183e

[purva-thakre]

This is not a hill I'd like to die on, however. Again, just a vanity thing.

No need to die on this hill @natestemen. Fixed in cc6704a

While it's a topic of discussion, however, would tag be more appropriate here than tag?

Is there a typo in this line?

[cosenal]

Honestly I don't know what I would prefer, whether dying on a hill, or becoming a cow stuck between two tags 😭

[purva-thakre]

Merging this after the community call discussion.