docs(create_rstfiles): order the notebook galleries by when a notebook was added

[jdhughes-dev]

• The notebook galleries were built from an alphabetical list, so a new notebook landed wherever its name fell rather than at the end
• Notebooks are now ordered by the commit that added them, and one that is not in the history yet sorts last
• Notebooks added in the same commit keep their alphabetical order, so most of the galleries are unchanged
• The order falls back to alphabetical when the history is not available, as in a shallow clone, rather than failing the documentation build

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.8%. Comparing base (556c088) to head (c2be913).
⚠️ Report is 187 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2792      +/-   ##
===========================================
+ Coverage     55.5%    72.8%   +17.2%     
===========================================
  Files          644      662      +18     
  Lines       124135   133001    +8866     
===========================================
+ Hits         68947    96828   +27881     
+ Misses       55188    36173   -19015     

see 583 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Updates the docs gallery generation script to order tutorial/example notebook listings by the commit timestamp when each notebook was first added (with graceful fallback to alphabetical ordering when Git history is unavailable).

Changes:

• Introduces an added_order() sort key that queries git log --diff-filter=A for each notebook’s “added” timestamp.
• Uses that sort key when building tutorials.rst and examples.rst notebook lists, instead of purely alphabetical ordering.
• Preserves alphabetical ordering as a tie-breaker and provides a fallback when history cannot be queried.

Suppressed comments (1)

.docs/create_rstfiles.py:104

• This sorts all notebook files and only then filters by name, which does extra added_order() work (and extra git log calls) for notebooks that will be discarded. Filtering first and then sorting only the relevant subset avoids that overhead.

    filenames = [
        path.name
        for path in sorted(nbs_path.rglob("*.py"), key=added_order)
        if "example" in path.name
    ]

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[jdhughes-dev]

All three fixed in c2be913.

The pathspec is now relative to the repository, so git log gets what it expects rather than an absolute path. The sentinel is float("inf") instead of 2**31, which was going to stop sorting an unreleased notebook last in 2038. The key is cached with lru_cache, which matters because the tutorials and the examples each sort the same notebooks.

[jdhughes-dev]

Fixed in c2be913, in both places. The notebooks are filtered by name before they are sorted.

Together with caching the key that is 84 calls to git log rather than 174, and the whole of create_rstfiles.py runs in about a second.