make sphinx Breaks when Certain Untracked Files are Present
#2404
Comments
|
The first case is easier to solve, the second is not possible as far as I'm aware -- Sphinx has no way to specify a whitelist of files -- the A |
|
I'm not familiar with how Sphinx works. It is surprising, though, that it can't handle the case. IIUC, it is blindly walking the entire directory tree and doesn't support a wildcard whitelist. What does it need to recurse in the PEP repo? |
You're right. And I'd ask the same question on default recursion. One thing that might be possible is adding A |
|
Sorry for the delay responding; I've been dealing with urgent family issues most of today. Good catch. It seems like the issue is ultimately due to having to try to render files with the legacy However, since full Unix-style glob syntax is supported in I implemented and tested this on some sample files in the root and subdirectories (including your example, and a few with varying degrees of similar names), and it excluded all of them, while not excluding any valid PEPs. Therefore, I opened PR #2405 which fixes this. |
|
I think the big difference here to "normal" Sphinx docs builds is we're reading the source documentation files from the root, and trying to ignore certain support and any other random user files. Whereas normal Sphinx builds virtually always read source files from a subdirectory such as
Is it feasible to move our source PEP files into a subdirectory? Can/should Sphinx be made to ignore |
Last time mass moves were done, it was reverted due to the GitHub interface: #462 (comment) This is still the case: https://github.com/python/peps/commits/main/.github/workflows/render.yml (the blame UI does track moves, though -- a fun inconsistency). A |
Please don't. The text in this repo isn't about the project in the repo, it is the project. |
|
@hugovk see #2405 for a general-case fix.
The other even bigger difference, that is more directly the problem in this case, is that for legacy reasons, the older PEPs have the
To be clear, given the GitHub UI limitations and general churn I don't believe its worth changing now (when, at least for this problem, a relatively straightforward fix is available). However, for what it's worth, I don't really understand this reasoning. In almost any sort of medium to large project, source content goes in a subdir—for Python projects, On this repo in particular, it harms UX, on GitHub and locally, since page after page of PEPs have to be scrolled through to read the Readme on GitHub, or get from the files that have names before |
|
I think the issue I'm seeing trying to build locally is this one (rather than #2402), since the linting works fine, but the rendering is complaining about old files inside the I'll try the #2415 branch to see if that resolves the issue. |
|
Thanks for testing! Whichever of #2405 and #2415 we go for (I'm leaning towards #2405), let's explicitly exclude I'll also repeat this question, my original typo made no sense :)
|
Maybe. A lot more work though. Also two approaches (files tracked by A |
See comments there; in short, this is only needed if we really want a very short-term stopgap until one of those PRs is merged.
This does seem like a lot more work, even more so than #2415 , which solves the issue much more precisely. |
make sphinxfails if I have some file like "pep-0684-old.rst" (the filename regex in pep_sphinx_extensions/pep_zero_generator/pep_index_generator.py isn't precise enough)make sphinxfails if I have a venv dir named "venv-spam" sitting at the top of the repo (tries to parse a vendor.txt file inside the venv)In both cases I'd expect it to work fine, ignoring the relevant files.
The text was updated successfully, but these errors were encountered: