Add initial README.md for tests/ requirement files #2577
Conversation
tests/README.md
Outdated
| # Requirements Files, and their uses | ||
| | File | Purpose | | ||
| | ---- | ------- | | ||
| |constraints.in | Pins for the stable, tested versions of sphinx and antsibull-docs that production builds rely upon | |
There was a problem hiding this comment.
Technically, not just pins. Actually, pins should be avoided in there mostly. Only specific version exclusions and rare top boundaries should go here. What's known to be broken (temporarily).
There was a problem hiding this comment.
I pulled the language right out of the file. Is there a better way to phrase it?
Something like "Pins, upper or lower version boundaries for known issues"
tests/README.md
Outdated
| |tag.in | Requirements for `tag` nox session | | ||
| |typing.in | Requirements for `typing` nox session | | ||
| |formatters.txt | Output of `uv pip compile --universal --output-file tests/formatters.txt -r tests/formatters.in` | | ||
| |pip-compile.txt | Output of `uv pip compile --universal --output-file tests/pip-compile.txt tests/pip-compile.in` | |
There was a problem hiding this comment.
txt files are pins (pip constraints really)
There was a problem hiding this comment.
Maybe add a separate column for txt files mapped to in? It's mostly 1:1.
There was a problem hiding this comment.
Maybe add a separate column for txt files mapped to in? It's mostly 1:1.
As in, move the *.txt files to another column on the lines with *.in files, as opposed to their own lines?
That sounds totally reasonable. Then maybe (if its useful to know?) just a singular blurb that *.in is compiled into the corresponding *.txt with the general form of the uv pip compile command.
Update Heading, per @oraNod's suggestion Co-authored-by: Don Naro <[email protected]>
|
@webknjaz can you take a look and see if that's in line with what you're suggesting both for the updates to the description on |
Co-authored-by: Sandra McCann <[email protected]>
Co-authored-by: Sandra McCann <[email protected]>
|
The CI failures here I think are unrelated to this PR so.. .bear with while we chase down the problems. |
|
gonna close/reopen to see if the CI problems go away |
|
Could you replace "requirements" with "dependencies" in the table? |
tests/README.md
Outdated
| |formatters.in | List of Formatters required | formatters.txt | | ||
| |pip-compile.in | Dependencies for `pip-compile` nox session | pip-compile.txt | | ||
| |pr_labeler.in | Dependencies for pr_labeler | pr_labeler.txt | | ||
| |requirements.in | Dependencies file for Docs Build | requirements.txt | |
There was a problem hiding this comment.
| |requirements.in | Dependencies file for Docs Build | requirements.txt | | |
| |requirements.in | Dependencies file for Sphinx doc builds | requirements.txt | |
Co-authored-by: Don Naro <[email protected]>
Co-authored-by: Don Naro <[email protected]>
|
@oraNod I think I have all your suggestions applied correctly. I'd appreciate another once-over to confirm |
|
thinking about branching devel to cut new stable releases. certain of the workflow files are deleted and kept on devel only. the corresponding requirements files are also deleted, which means this doc would not reflect what is on the stable branches. we could note this in the MAINTAINERS.md file and say to either modify or delete this table. |
First pass at adding documentation requested in #312 I did this as a table because that's the format that made sense to me, but if other have a different approach, or what other information included, I'm happy to improve from here.
Fixes #312