Add idle help check to CI

Author: StanFromIreland

.github/workflows/build.yml

@@ -49,6 +49,11 @@ jobs:
     if: fromJSON(needs.build-context.outputs.run-docs)
     uses: ./.github/workflows/reusable-docs.yml
 
+  check-idle-help-doc:
+    name: "Check if IDLE's help.html is up to date"
+    needs: check-docs
+    uses: ./.github/workflows/reusable-idle-help-doc.yml
+
   check-autoconf-regen:
     name: 'Check if Autoconf files are up to date'
     # Don't use ubuntu-latest but a specific version to make the job
@@ -711,8 +716,16 @@ jobs:
           build-ubuntu-ssltests-openssl,
           test-hypothesis,
           cifuzz,
+          check-idle-help-doc,
         allowed-skips: >-
-          ${{ !fromJSON(needs.build-context.outputs.run-docs) && 'check-docs,' || '' }}
+          ${{
+            !fromJSON(needs.build-context.outputs.run-docs)
+            && '
+            check-docs,
+            check-idle-help-doc,
+            '
+            || ''
+          }}
           ${{
             needs.build-context.outputs.run-tests != 'true'
             && '

.github/workflows/reusable-docs.yml

@@ -75,6 +75,12 @@ jobs:
           --fail-if-regression \
           --fail-if-improved \
           --fail-if-new-news-nit
+    - name: 'Upload built idle.html'
+      uses: actions/upload-artifact@v4
+      with:
+        name: idle-html
+        path: Doc/build/html/library/idle.html
+        retention-days: 1
 
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:

.github/workflows/reusable-idle-help-doc.yml

@@ -0,0 +1,45 @@
+name: Reusable check if IDLE's help.html is up to date
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  check-idle-doc-sync:
+    name: 'Check IDLE help.html sync'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10 # XXX run and possibly lower!
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: 'Download built idle.html'
+      uses: actions/download-artifact@v4
+      with:
+        name: idle-html
+        path: Doc/build/html/library
+    - name: 'Set up Python'
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3'
+    - name: 'Regenerate Lib/idlelib/help.html'
+      run: python Tools/build/generate_idle_help.py
+      working-directory: Doc
+    - name: 'Check for changes'
+      run: |
+          git add -u
+          changes=$(git status --porcelain)
+          # Check for changes in regenerated files
+          if test -n "$changes"; then
+            echo "Generated files not up to date."
+            echo "Perhaps you forgot to run make idlehelp ;)"
+            echo "$changes"
+            echo ""
+            git diff --staged || true
+            exit 1
+          fi

Doc/Makefile

@@ -46,6 +46,7 @@ help:
 	@echo "  coverage   to check documentation coverage for library and C API"
 	@echo "  doctest    to run doctests in the documentation"
 	@echo "  pydoc-topics  to regenerate the pydoc topics file"
+	@echo "  idlehelp   to regenerate Lib/idlelib/help.html"
 	@echo "  dist       to create a \"dist\" directory with archived docs for download"
 	@echo "  check      to run a check for frequent markup errors"
 
@@ -143,6 +144,10 @@ pydoc-topics: build
 	      "cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py" \
 	      "&& cp build/pydoc-topics/module_docs.py ../Lib/pydoc_data/module_docs.py"
 
+.PHONY: idlehelp
+idlehelp: html
+	$(PYTHON) ../Tools/build/generate_idle_help.py
+
 .PHONY: gettext
 gettext: BUILDER = gettext
 gettext: override SPHINXOPTS := --doctree-dir build/doctrees-gettext $(SPHINXOPTS)

Lib/idlelib/help.html

@@ -248,43 +248,6 @@ def __init__(self, parent, filename, title):
         self.grid_rowconfigure(0, weight=1)
 
 
-def copy_strip():  # pragma: no cover
-    """Copy the text part of idle.html to idlelib/help.html while stripping trailing whitespace.
-
-    Files with trailing whitespace cannot be pushed to the git cpython
-    repository.  For 3.x (on Windows), help.html is generated, after
-    editing idle.rst on the master branch, with
-      sphinx-build -bhtml . build/html
-      python_d.exe -c "from idlelib.help import copy_strip; copy_strip()"
-    Check build/html/library/idle.html, the help.html diff, and the text
-    displayed by Help => IDLE Help.  Add a blurb and create a PR.
-
-    It can be worthwhile to occasionally generate help.html without
-    touching idle.rst.  Changes to the master version and to the doc
-    build system may result in changes that should not change
-    the displayed text, but might break HelpParser.
-
-    As long as master and maintenance versions of idle.rst remain the
-    same, help.html can be backported.  The internal Python version
-    number is not displayed.  If maintenance idle.rst diverges from
-    the master version, then instead of backporting help.html from
-    master, repeat the procedure above to generate a maintenance
-    version.
-    """
-    src = join(abspath(dirname(dirname(dirname(__file__)))),
-            'Doc', 'build', 'html', 'library', 'idle.html')
-    dst = join(abspath(dirname(__file__)), 'help.html')
-
-    with open(src, 'r', encoding="utf-8") as inn, open(dst, 'w', encoding="utf-8") as out:
-        copy = False
-        for line in inn:
-            if '<section id="idle">' in line: copy = True
-            if '<div class="clearer">' in line: break
-            if copy: out.write(line.strip() + '\n')
-
-    print(f'{src} copied to {dst}')
-
-
 def show_idlehelp(parent):
     "Create HelpWindow; called from Idle Help event handler."
     filename = join(abspath(dirname(__file__)), 'help.html')

Lib/idlelib/help.py

@@ -0,0 +1,41 @@
+"""Copy the text part of idle.html to idlelib/help.html while stripping trailing whitespace.
+
+Files with trailing whitespace cannot be pushed to the git cpython
+repository.  help.html is regenerated, after
+editing idle.rst on the master branch, with, in the Doc directory
+  make idlehelp
+Check build/html/library/idle.html, the help.html diff, and the text
+displayed by Help => IDLE Help.  Add a blurb and create a PR.
+
+It can be worthwhile to occasionally generate help.html without
+touching idle.rst.  Changes to the master version and to the doc
+build system may result in changes that should not change
+the displayed text, but might break HelpParser.
+
+As long as master and maintenance versions of idle.rst remain the
+same, help.html can be backported.  The internal Python version
+number is not displayed.  If maintenance idle.rst diverges from
+the master version, then instead of backporting help.html from
+master, repeat the procedure above to generate a maintenance
+version.
+"""
+
+def copy_strip():
+    src = 'build/html/library/idle.html'
+    dst = '../Lib/idlelib/help.html'
+
+    with open(src, encoding="utf-8") as inn, open(dst, 'w', encoding="utf-8") as out:
+        copy = False
+        for line in inn:
+            if '<div class="clearer">' in line:
+                break
+            if '<section id="idle">' in line:
+                copy = True
+            if copy:
+                out.write(line.strip() + '\n')
+
+    print(f'{src} copied to {dst}')
+
+
+if __name__ == '__main__':
+    copy_strip()