Qiskit / Qiskit/documentation

Make API dev docs images deterministic

Open
#2,517 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

content 📄 infra 🏗️
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.