gh-69405: Add check for idle's help.html to CI

[StanFromIreland]

I expect it to fail till #143718 is merged.

I had to refactor copy_strip to a separate file to avoid having to build Python.

• Issue: Automate creation of idlelib/help.html from Doc/.../idle.html #69405

---

📚 Documentation preview 📚: https://cpython-previews--143742.org.readthedocs.build/

🏃 Run preview 🏃: https://github.com/python/cpython/actions/runs/20930506392/job/60140508484?pr=143742

[StanFromIreland]

A downside of how I currently have it is that it need the entire docs job to finish (i.e. it includes waiting for the doc tests), we could have it run earlier by moving it under the docs job (though I don't think that is particularly nice), however since it runs in 7 seconds I think it is a negligible issue.

[StanFromIreland]

@webknjaz could you please take a peek at this?

[hugovk]

Should this new job also be required by "All required checks pass"?

https://github.com/python/cpython/actions/runs/20930506392?pr=143742

---

A downside of how I currently have it is that it need the entire docs job to finish (i.e. it includes waiting for the doc tests), we could have it run earlier by moving it under the docs job (though I don't think that is particularly nice), however since it runs in 7 seconds I think it is a negligible issue.

The time isn't a problem, but there's quite a bit of extra complexity and config to achieve this, when it could be ~10 extra lines to add a couple of steps to the existing docs job.

[hugovk]

Could this stay in Lib/idlelib/help.py?

[StanFromIreland]

We would have to build CPython if we want to be able to modify it, that's not particularly fast?

[terryjreedy]

I don't understand the purported need to move copy_strip (and fairly strongly prefer not to). What is 'it'? I cannot imagine a need to modify the code just to check the file modification state.

I am not sure about adding a new make target. Currently, I update help.html (either in a .bat or manually) with
python -c "from idlelib.help import copy_strip; copy_strip()" in the repository, so that 'python' is the repository build and the update happens in the repository. I don't know if there is the equivalent for non-Windows, but copy pasting this command into command prompt is easier than changing directories and invoking make. I would personally prefer a reminder to run the above than to find make.

[StanFromIreland]

If we don’t want to move, currently it is useless where it is with a system python, as the paths are relative to the location of the installed idlelib, and the Doc folder is not in /usr/lib/ or somewhere like that.

We could update the function, but then we would have to wait for the next 3.14 release (and then for actions to pick it up) before we could it.

The other option is building CPython, but that would just make the check over 50x times slower.

[StanFromIreland]

Should this new job also be required by "All required checks pass"?

Terry asked me to not make it required on the issue.

[terryjreedy]

This is getting messy, so lets back up. IDLE's objective is to make an offlline frozen copy of its doc available. At one time, the Windows installer installed propriety .chm files derived from the .html files. IDLE's F1 brought up the python .chm index. I believe that this was true at the time the IDLE doc display, using the help.html copy, was added.

Currently, the Windows installer installs the Doc/build/html tree beside python.exe and F1 displays index.html. Ditto for macOS, though the location is more obscure. In either case, Modules/idlelib displays idle.html. So on Windows and Mac, the local copy is not needed. I don't know what the situation is on Linux and *nix in general, but I have the impression that at least some distributions also include the docs with Python. So maybe we can make this issue moot.

EDIT: I could look for the F1 code to see what it does on *nix, but I need sleep.

[terryjreedy]

Is it the case that make can run Python with a file argument but not a -c "code" argument?

[StanFromIreland]

No, make can handle it.

[terryjreedy]

It appears that rather than compare last change dates you are making a potentially revised file and looking for a non-empty diff (but not committing). The latter seems much harder. Is yaml unable to do the former?

[StanFromIreland]

Are you suggesting we simply fail if idle.rST is modified?

[webknjaz]

FTR, if the only check we want here is comparing last edit dates of two files, I'd place it in makefile and would drop that separate step. Though, the semantics of such a check is unclear — the timestamps are likely to differ by seconds unless there's an automation that sets these to the same value. It seems like the only reliable check would be whether their last change happened in the same Git commit, if I understand the implied relation between the two files.

[terryjreedy]

I don't understand the purported need to move copy_strip (and fairly strongly prefer not to). What is 'it'? I cannot imagine a need to modify the code just to check the file modification state.

I am not sure about adding a new make target. Currently, I update help.html (either in a .bat or manually) with
python -c "from idlelib.help import copy_strip; copy_strip()" in the repository, so that 'python' is the repository build and the update happens in the repository. I don't know if there is the equivalent for non-Windows, but copy pasting this command into command prompt is easier than changing directories and invoking make. I would personally prefer a reminder to run the above than to find make.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[webknjaz]

I'd prefer passing Doc/build/html/library/ between the jobs too: an artifact is an abstract'ish GHA concept for "some/arbitrary files stored for later use" and the path is where to put it when downloading+uploading. But together, the the pair of artifact ID+path to unpack it, is something that shouldn't be maintained in two disconnected contexts w/ an implicit expectation that somebody will keep them in sync.
Though, this would require another step to store it into an output and reuse here + workflow outputs. We could probably pack both into the same output as a JSON string so they aren't separated in refactorings...

[StanFromIreland]

include the docs with Python.

Some Linux distributions do (often not installed by default, as is done with IDLE), but, Terry, I don't quite understand what you want to achieve with this check?
Problems are best caught before they make it into prod (i.e. checking PRs), if we compare against the released copy it seems a bit late for that?

For the check, I think the best option is moving copy_strip() out from the standard library, otherwise we cannot use the latest version in the step (further on that point, currently it is unusable if installed, since paths are relative to it).