Skip to content

[codex] Skip missing static file sources#4122

Open
Sean-Kenneth-Doherty wants to merge 2 commits into
mkdocs:masterfrom
Sean-Kenneth-Doherty:fix/dangling-symlink-static-file
Open

[codex] Skip missing static file sources#4122
Sean-Kenneth-Doherty wants to merge 2 commits into
mkdocs:masterfrom
Sean-Kenneth-Doherty:fix/dangling-symlink-static-file

Conversation

@Sean-Kenneth-Doherty
Copy link
Copy Markdown

Summary

  • catch missing static file sources during copy and warn instead of aborting the build
  • handle dirty builds where is_modified() can raise before copy reaches the missing-source warning
  • add clean and dirty copy tests for missing source paths

Why

Broken symlinks or files that disappear after discovery currently raise FileNotFoundError while MkDocs is copying static files. There is an older related PR in #3785; this keeps the fix local to File.copy_file, avoids release/version churn, and adds focused test coverage including dirty-copy behavior.

Validation

  • git diff --check
  • hatch run test.py3.12-default:python -m unittest mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_missing_source mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_dirty_missing_source
  • hatch run test.py3.12-default:python -m unittest mkdocs.tests.structure.file_tests
  • clean mkdocs build repro with a broken docs symlink completes with WARNING - File skipped: ... does not exist.
  • dirty mkdocs build --dirty repro after breaking a previously valid symlink completes with the same warning
  • hatch run style:check

@Sean-Kenneth-Doherty
Copy link
Copy Markdown
Author

CI note from the first run:

  • The CPython failures are in test_draft_docs_with_comments_from_user_guide, with other_unpublished.html unexpectedly built / missing the preview log assertion. That is the draft-docs fixture indentation issue fixed separately in Use PyPy 3.11 in CI #4121.
  • The PyPy 3.9 Ubuntu/Windows failures are the current Hatch dependency bootstrap issue (cryptography 48 / PyO3 requiring PyPy 3.11), also covered by Use PyPy 3.11 in CI #4121.

I am keeping this branch scoped to the missing static-file source behavior instead of copying those CI-only fixes into this PR.

@Sean-Kenneth-Doherty
Copy link
Copy Markdown
Author

Follow-up after the rerun: the code/test failures from the first matrix are gone. The only remaining red checks are both PyPy 3.9 dependency bootstrap failures before MkDocs tests run:

  • test (pypy-3.9-v7.x, ubuntu-latest): python -m pip install --upgrade hatch falls into building cryptography from source and fails in the PyO3 build (pyo3-ffi).
  • test (pypy-3.9-v7.x, windows-latest): the same hatch install path falls into building zstandard from source and fails through CFFI/distutils (No module named 'distutils.msvc9compiler').

All CPython, macOS PyPy, lint, style, build, and package jobs are green on this head. This matches the PyPy 3.9 CI bootstrap drift addressed separately by #4120 rather than a failure in this static-file change.

@Sean-Kenneth-Doherty Sean-Kenneth-Doherty marked this pull request as ready for review May 17, 2026 04:13
@Sean-Kenneth-Doherty
Copy link
Copy Markdown
Author

I pushed a small follow-up (e99222bf) to dedent the existing draft_docs user-guide fixture. The first CI run exposed the same pathspec 1.x parsing issue seen on the PyPy CI PR; after the follow-up, the CPython and macOS PyPy test lanes that reach the test suite are green.

Fresh local validation on the current branch:

  • TMPDIR=$PWD/.tmp-test .venv/bin/python -m unittest mkdocs.tests.build_tests.BuildTests.test_draft_docs_with_comments_from_user_guide mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_missing_source mkdocs.tests.structure.file_tests.TestFiles.test_copy_file_dirty_missing_source -v -> passed
  • TMPDIR=$PWD/.tmp-test .venv/bin/python -m unittest mkdocs.tests.structure.file_tests -v -> passed (34 tests, OK (skipped=1))
  • TMPDIR=$PWD/.tmp-test .venv/bin/python -m unittest discover -s mkdocs -p '*tests.py' -> passed (727 tests, OK (skipped=4))
  • uvx --with pip hatch run style:check -> passed
  • git diff --check origin/master...HEAD -> clean

Current GitHub Actions after the follow-up: build/lint/package/style and all CPython test lanes are passing. The remaining red lanes are the existing PyPy 3.9 dependency-install failures, before tests run: Ubuntu fails building cryptography because PyO3 now requires PyPy >= 3.11, and Windows fails building zstandard through the hosted PyPy 3.9/CFFI distutils path. Those are unrelated to this missing-static-source fix and are covered by #4120.

@Sean-Kenneth-Doherty
Copy link
Copy Markdown
Author

CI note: the two red PyPy 3.9 jobs are failing before the MkDocs test suite starts, during the workflow dependency install step (python -m pip install --upgrade hatch).

  • pypy-3.9-v7.x, ubuntu-latest: Hatch dependency resolution reaches cryptography, which builds from source and fails in pyo3-ffi with the configured PyPy interpreter version (3.9) is lower than PyO3's minimum supported version (3.11).
  • pypy-3.9-v7.x, windows-latest: Hatch dependency resolution reaches zstandard, which builds from source and fails in CFFI with ModuleNotFoundError: No module named 'distutils.msvc9compiler' / This CFFI feature requires distutils.\n\nThe macOS PyPy job and all CPython test jobs passed, so I do not see evidence that this branch changed MkDocs behavior on PyPy; this looks like dependency/tooling drift in the PyPy 3.9 CI environment.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant