Make API dev docs images deterministic
Nobody has claimed this yet.
- Dominant language
- Jupyter Notebook
- Stars
- 106
- Forks
- 223
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 72
Description
I'm reading that binary files are particularly bad for Git repo size. Beyond Git repo size, the diff is annoying that ever time we generate dev API docs, we have unrelated image changes, like https://github.com/Qiskit/documentation/pull/2509.
So, see if we can make the images deterministic, even a few of them. We're not worried about changes resulting from when changes are made to the docs themselves, such as indexes shifting; the goal is that generating the same docs stays the same.
I'm not sure the particular ways to fix things, like the snippets to use. However, Qiskit tests often use techniques like setting the seed (for random number generation) to be deterministic. You can test if your fix worked by re-generating the Sphinx docs in the Qiskit and Runtime repositories with tox -e docs-clean; tox -e docs.
Update Jan 10, 2025: this is less urgent because of AVIF images making images ~10% the size. However, it's still good to fix.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by running tox -e docs-clean; tox -e docs in the Qiskit and Runtime repositories and inspect the generated Sphinx API documentation images for changes between identical builds. Investigate the image-generation inputs and deterministic-seeding techniques used by Qiskit tests. Done means repeated generation produces unchanged images unless the documentation itself changes.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, documentation
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100