diff --git a/.docs/create_rstfiles.py b/.docs/create_rstfiles.py index b63a70c56..a2d99a62d 100644 --- a/.docs/create_rstfiles.py +++ b/.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: