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

.docs/create_rstfiles.py

@@ -1,8 +1,34 @@
+import subprocess
+from functools import lru_cache
 from pathlib import Path
 
 project_root_path = Path(__file__).parent.parent
 
 
+@lru_cache(maxsize=None)
+def added_order(path):
+    """Sort key that puts notebooks in the order they were added
+
+    Notebooks added in the same commit keep their alphabetical order, and one
+    that is not in the history yet sorts last.  The order falls back to
+    alphabetical when the history is not available, as in a shallow clone.
+    """
+    try:
+        # git wants a pathspec relative to the repository it is run in
+        pathspec = str(path.relative_to(project_root_path))
+        added = subprocess.run(
+            ["git", "log", "--diff-filter=A", "--format=%at", "-1", "--", pathspec],
+            capture_output=True,
+            text=True,
+            cwd=project_root_path,
+            timeout=10,
+            check=False,
+        ).stdout.strip()
+    except (OSError, ValueError, subprocess.SubprocessError):
+        added = ""
+    return (float(added) if added else float("inf"), path.name)
+
+
 def get_section(f):
     lines = Path(f).open().readlines()
     line = next(iter([l for l in lines if "#     section:" in l]), None)
@@ -33,9 +59,13 @@ def create_gallery_section(f, name, title, stems):
 def create_tutorials_rst():
     rst_path = project_root_path / ".docs" / "tutorials.rst"
     nbs_path = project_root_path / ".docs" / "Notebooks"
-    filenames = sorted(
-        [path.name for path in nbs_path.rglob("*.py") if "tutorial" in path.name]
-    )
+    filenames = [
+        path.name
+        for path in sorted(
+            (p for p in nbs_path.rglob("*.py") if "tutorial" in p.name),
+            key=added_order,
+        )
+    ]
 
     print(f"Creating {rst_path}")
     with open(rst_path, "w") as rst_file:
@@ -73,9 +103,13 @@ def create_tutorials_rst():
 def create_examples_rst():
     rst_path = project_root_path / ".docs" / "examples.rst"
     nbs_path = project_root_path / ".docs" / "Notebooks"
-    filenames = sorted(
-        [path.name for path in nbs_path.rglob("*.py") if "example" in path.name]
-    )
+    filenames = [
+        path.name
+        for path in sorted(
+            (p for p in nbs_path.rglob("*.py") if "example" in p.name),
+            key=added_order,
+        )
+    ]
 
     print(f"Creating {rst_path}")
     with open(rst_path, "w") as rst_file: