Fix: avoid indefinite Sphinx build freeze from unbounded git log call

[suhr25]

Summary

This PR fixes a blocking issue in _ext/last_edition.py where a git log subprocess is executed without a timeout inside the html_page_context hook.

Since html_page_context runs once per page during Sphinx builds, the following code path is executed repeatedly:

last_datetime_raw = subprocess.check_output(
    (
        "git",
        "--git-dir",
        git_dir,
        "log",
        "-1",
        "--pretty=format:%ci",
        "--",
        f"{pagename}{context['page_source_suffix']}",
    )
).decode()

Without a timeout, any delay/hang in git (repo lock, concurrent git operations, slow filesystem, etc.) can block the entire Sphinx build indefinitely. This is especially noticeable with sphinx-autobuild, where one stuck build prevents subsequent rebuilds.

Fix

The subprocess call is now bounded with a timeout and handles timeout failures gracefully:

last_datetime_raw = subprocess.check_output(
    (...),
    timeout=5,
).decode()
except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
    return

Key improvements

• Prevents indefinite blocking of Sphinx builds
• Ensures builds continue even if git is slow/unavailable
• Gracefully skips last_edition metadata for affected pages
• Minimal, localized change; normal fast-path remains unchanged

Verification

• Ran sphinx-autobuild locally and confirmed rebuilds continue under simulated git delays (e.g., temporary repo lock / slow response)
• Confirmed normal behavior is unchanged when git log executes quickly

[suhr25]

Hi @unman ,
All checks are passing and this fix prevents sphinx autobuild from hanging due to unbounded git calls.
Would appreciate a quick review when you have time, thanks!

[parulin]

Maybe it would be even better to only include this extension in specific situations, in conf.py:

if os.environ.get('READTHEDOCS') or os.environ.get('QUBES_DOC_FULL_BUILD'):
    extensions.append('last_edition')

[suhr25]

Hi @parulin @unman,

I’ve addressed the feedback: reduced the timeout (now configurable via env var), added the missing exception handling, and gated last_edition in conf.py to only run on READTHEDOCS / full builds.
Thanks!

[parulin]

Ok, nice. Sorry, but I think that now, we also need to document those variables, maybe in /developer/general/how-to-edit-the-rst-documentation:Building the rST documentation locally... It could also be part of another PR.

[suhr25]

Hi @parulin @unman @maiska,
Thanks for the suggestion! I’ve added documentation for the new environment variables in
developer/general/how-to-edit-the-rst-documentation.rst.

Please take a look.

[parulin]

No need to mention everyone.

I made a PR to your personal repo to avoid more work for you. I will try to merge our two versions and update it.

[parulin]

Just a few tips about the documentation style guide:

• no hardwrap, yes it is confusing: Confusing mention of "hard wrap" in the documentation style guide qubes-issues#10221

• no need to put a label to reference a title if you do not use it:

  .. _something:
  Title
  ^^^^^

  Is only useful if you have the following somewhere:

  :ref:`something`

[suhr25]

Thanks for the improvements and the style guidance. I will align with the no hardwrap rule going forward.

[suhr25]

@parulin
I merged the updates from the PR you opened on my fork . Please take another look.
Thanks!

[parulin]

There is nothing new to review for me.

[suhr25]

Let me know if anything else is needed from my side.

[suhr25]

@parulin,
I updated the PR to follow the documentation style guide: removed unused .. _label: anchors and ensured paragraphs are not hard wrapped. The functional change remains the same .