From 3751b6b030b4a3b88959b4f3c4ef2e58d325e497 Mon Sep 17 00:00:00 2001 From: Steve Dower Date: Tue, 22 Mar 2022 01:08:37 +0000 Subject: [PATCH] bpo-47086: Remove .chm from Windows installer and add HTML docs (GH-32038) --- .azure-pipelines/windows-release.yml | 7 +++- .azure-pipelines/windows-release/gpg-sign.yml | 3 ++ .../windows-release/msi-steps.yml | 2 - .../windows-release/stage-build.yml | 8 +--- .../stage-publish-pythonorg.yml | 8 +++- .../2022-03-21-20-45-01.bpo-47086.bIuKlF.rst | 2 + PC/layout/support/filesets.py | 2 + PC/layout/support/options.py | 2 +- Tools/msi/README.txt | 40 ++++++++----------- Tools/msi/build.bat | 6 +-- Tools/msi/buildrelease.bat | 2 +- Tools/msi/bundle/Default.wxl | 2 +- Tools/msi/common.wxs | 4 +- Tools/msi/doc/doc.wixproj | 25 +++++++----- Tools/msi/doc/doc.wxs | 24 +++++------ Tools/msi/doc/doc_files.wxs | 15 ------- Tools/msi/doc/doc_no_files.wxs | 17 -------- Tools/msi/msi.props | 3 -- Tools/msi/uploadrelease.ps1 | 12 +++--- 19 files changed, 79 insertions(+), 105 deletions(-) create mode 100644 Misc/NEWS.d/next/Windows/2022-03-21-20-45-01.bpo-47086.bIuKlF.rst delete mode 100644 Tools/msi/doc/doc_files.wxs delete mode 100644 Tools/msi/doc/doc_no_files.wxs diff --git a/.azure-pipelines/windows-release.yml b/.azure-pipelines/windows-release.yml index 096ecadc79eb75..581f48ba22882b 100644 --- a/.azure-pipelines/windows-release.yml +++ b/.azure-pipelines/windows-release.yml @@ -43,13 +43,17 @@ parameters: # Eventually when we stop releasing anything that old, we can drop this # argument (and make it implicitly always 'true') - name: ARM64TclTk - displayName: "Use Tcl/Tk for ARM64" + displayName: "Use Tcl/Tk for ARM64 (3.11 and later)" type: boolean default: true - name: DoPGO displayName: "Run PGO" type: boolean default: true +- name: DoCHM + displayName: "Produce compiled help document (pre-3.11)" + type: boolean + default: false - name: DoLayout displayName: "Produce full layout artifact" type: boolean @@ -86,6 +90,7 @@ variables: ${{ if ne(parameters.SigningCertificate, 'Unsigned') }}: SigningCertificate: ${{ parameters.SigningCertificate }} SigningDescription: ${{ parameters.SigningDescription }} + DoCHM: ${{ parameters.DoCHM }} DoLayout: ${{ parameters.DoLayout }} DoMSIX: ${{ parameters.DoMSIX }} DoNuget: ${{ parameters.DoNuget }} diff --git a/.azure-pipelines/windows-release/gpg-sign.yml b/.azure-pipelines/windows-release/gpg-sign.yml index 0855af8d703df9..04206d23e4996f 100644 --- a/.azure-pipelines/windows-release/gpg-sign.yml +++ b/.azure-pipelines/windows-release/gpg-sign.yml @@ -3,12 +3,14 @@ parameters: GPGPassphrase: $(GPGPassphrase) Files: '*' WorkingDirectory: $(Build.BinariesDirectory) + Condition: succeeded() steps: - task: DownloadSecureFile@1 name: gpgkey inputs: secureFile: ${{ parameters.GPGKeyFile }} + condition: ${{ parameters.Condition }} displayName: 'Download GPG key' - powershell: | @@ -18,6 +20,7 @@ steps: gpg/gpg2.exe -ba --batch --passphrase ${{ parameters.GPGPassphrase }} $_ "Made signature for $_" } + condition: ${{ parameters.Condition }} displayName: 'Generate GPG signatures' workingDirectory: ${{ parameters.WorkingDirectory }} diff --git a/.azure-pipelines/windows-release/msi-steps.yml b/.azure-pipelines/windows-release/msi-steps.yml index c3c2c43032c00f..79fc6f5ed292d4 100644 --- a/.azure-pipelines/windows-release/msi-steps.yml +++ b/.azure-pipelines/windows-release/msi-steps.yml @@ -21,8 +21,6 @@ steps: inputs: sourceFolder: $(Build.BinariesDirectory)\doc targetFolder: $(Build.SourcesDirectory)\Doc\build - contents: | - htmlhelp\*.chm - task: DownloadPipelineArtifact@1 displayName: 'Download artifact: bin_win32' diff --git a/.azure-pipelines/windows-release/stage-build.yml b/.azure-pipelines/windows-release/stage-build.yml index 2745d79dd069ca..26f43177504362 100644 --- a/.azure-pipelines/windows-release/stage-build.yml +++ b/.azure-pipelines/windows-release/stage-build.yml @@ -5,7 +5,6 @@ jobs: - job: Build_Docs displayName: Docs build pool: - #name: 'Windows Release' vmImage: windows-2022 workspace: @@ -21,14 +20,10 @@ jobs: - script: Doc\make.bat htmlhelp displayName: 'Build CHM docs' + condition: and(succeeded(), eq(variables['DoCHM'], 'true')) env: BUILDDIR: $(Build.BinariesDirectory)\Doc - #- powershell: | - # mkdir -Force "$(Build.BinariesDirectory)\Doc\htmlhelp" - # iwr "https://www.python.org/ftp/python/3.8.0/python380.chm" -OutFile "$(Build.BinariesDirectory)\Doc\htmlhelp\python390a0.chm" - # displayName: 'Cheat at building CHM docs' - - task: CopyFiles@2 displayName: 'Assemble artifact: Doc' inputs: @@ -44,6 +39,7 @@ jobs: targetPath: $(Build.ArtifactStagingDirectory)\Doc artifactName: doc + - job: Build_Python displayName: Python build diff --git a/.azure-pipelines/windows-release/stage-publish-pythonorg.yml b/.azure-pipelines/windows-release/stage-publish-pythonorg.yml index 953f728ade3811..ee50e4e8aa0db0 100644 --- a/.azure-pipelines/windows-release/stage-publish-pythonorg.yml +++ b/.azure-pipelines/windows-release/stage-publish-pythonorg.yml @@ -87,7 +87,13 @@ jobs: - template: ./gpg-sign.yml parameters: GPGKeyFile: 'python-signing.key' - Files: 'doc\htmlhelp\*.chm, msi\*\*, embed\*.zip' + Files: 'msi\*\*, embed\*.zip' + + - template: ./gpg-sign.yml + parameters: + GPGKeyFile: 'python-signing.key' + Files: 'doc\htmlhelp\*.chm' + Condition: and(succeeded(), eq(variables['DoCHM'], 'true')) - powershell: > $(Build.SourcesDirectory)\Tools\msi\uploadrelease.ps1 diff --git a/Misc/NEWS.d/next/Windows/2022-03-21-20-45-01.bpo-47086.bIuKlF.rst b/Misc/NEWS.d/next/Windows/2022-03-21-20-45-01.bpo-47086.bIuKlF.rst new file mode 100644 index 00000000000000..b73e1870c6de2c --- /dev/null +++ b/Misc/NEWS.d/next/Windows/2022-03-21-20-45-01.bpo-47086.bIuKlF.rst @@ -0,0 +1,2 @@ +The installer for Windows now includes documentation as loose HTML files +rather than a single compiled :file:`.chm` file. diff --git a/PC/layout/support/filesets.py b/PC/layout/support/filesets.py index 47f727c057844c..3f63f686a9fabb 100644 --- a/PC/layout/support/filesets.py +++ b/PC/layout/support/filesets.py @@ -93,6 +93,8 @@ def _return_true(f): def rglob(root, patterns, condition=None): + if not os.path.isdir(root): + return if isinstance(patterns, tuple): for p in patterns: yield from _rglob(root, p, condition or _return_true) diff --git a/PC/layout/support/options.py b/PC/layout/support/options.py index 9faf20c0fdc7a1..e8310293159e4c 100644 --- a/PC/layout/support/options.py +++ b/PC/layout/support/options.py @@ -80,7 +80,7 @@ def public(f): "venv", "dev", "symbols", - "chm", + "html-doc", ], }, "embed": { diff --git a/Tools/msi/README.txt b/Tools/msi/README.txt index 0a4382f3e0223e..8c6ec516f18e9d 100644 --- a/Tools/msi/README.txt +++ b/Tools/msi/README.txt @@ -4,17 +4,16 @@ Quick Build Info For testing, the installer should be built with the Tools/msi/build.bat script: - build.bat [-x86] [-x64] [--doc] + build.bat [-x86] [-x64] [-ARM64] [--doc] For an official release, the installer should be built with the Tools/msi/buildrelease.bat script and environment variables: - set PYTHON= + set PYTHON= set SPHINXBUILD= - set PATH=; - ;%PATH% + set PATH=;%PATH% - buildrelease.bat [-x86] [-x64] [-D] [-B] + buildrelease.bat [-x86] [-x64] [-ARM64] [-D] [-B] [-o ] [-c ] See the Building the Installer section for more information. @@ -77,20 +76,17 @@ and Features | Turn Windows Features on or off) and ensure that the entry For testing, the installer should be built with the Tools/msi/build.bat script: - build.bat [-x86] [-x64] [--doc] [--test-marker] [--pack] + build.bat [-x86] [-x64] [-ARM64] [--doc] [--test-marker] [--pack] This script will build the required configurations of Python and generate an installer layout in PCbuild/(win32|amd64)/en-us. -Specify -x86 and/or -x64 to build for each platform. If neither is -specified, both platforms will be built. Currently, both the debug and +Specify -x86, -x64 and/or -ARM64 to build for each platform. If none are +specified, both x64 and x86 will be built. Currently, both the debug and release versions of Python are required for the installer. -Specify --doc to build the documentation (.chm) file. If the file is not -available, it will simply be excluded from the installer. Ensure -%PYTHON% and %SPHINXBUILD% are set when passing this option. You may -also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC on -your PATH or in externals/. +Specify --doc to include the documentation files. Ensure %PYTHON% and +%SPHINXBUILD% are set when passing this option. Specify --test-marker to build an installer that works side-by-side with an official Python release. All registry keys and install locations will @@ -106,18 +102,18 @@ Tools/msi/buildrelease.bat script: set PYTHON= set SPHINXBUILD= - set PATH=; - ;%PATH% + set PATH=;%PATH% - buildrelease.bat [-x86] [-x64] [-D] [-B] + buildrelease.bat [-x86] [-x64] [-ARM64] [-D] [-B] [-o ] [-c ] -Specify -x86 and/or -x64 to build for each platform. If neither is -specified, both platforms will be built. Currently, both the debug and +Specify -x86, -x64 and/or -ARM64 to build for each platform. If none are +specified, both x64 and x86 will be built. Currently, both the debug and release versions of Python are required for the installer. Specify -D to skip rebuilding the documentation. The documentation is required for a release and the build will fail if it is not available. +Ensure %PYTHON% and %SPHINXBUILD% are set if you omit this option. Specify -B to skip rebuilding Python. This is useful to only rebuild the installer layout after a previous call to buildrelease.bat. @@ -129,10 +125,6 @@ Specify -c to choose a code-signing certificate to be used for all the signable binaries in Python as well as each file making up the installer. Official releases of Python must be signed. -Ensure %PYTHON% and %SPHINXBUILD% are set when passing this option. You -may also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC -on your PATH or in externals/. You will also need Git (git.exe) on -your PATH. If WiX is not found on your system, it will be automatically downloaded and extracted to the externals/ directory. @@ -366,7 +358,7 @@ Within this install directory is the following approximate layout: .\python3x.dll The core interpreter .\python3.dll The stable ABI reference .\DLLs Stdlib extensions (*.pyd) and dependencies -.\Doc Documentation (*.chm) +.\Doc Documentation (*.html) .\include Development headers (*.h) .\Lib Standard library .\Lib\test Test suite @@ -421,7 +413,7 @@ a semicolon. When the documentation is installed, a key "Help" is created within the root key, with a subkey "Main Python Documentation" with its default -value set to the full path to the installed CHM file. +value set to the full path to the main index.html file. The py.exe launcher is installed as part of a regular Python install, diff --git a/Tools/msi/build.bat b/Tools/msi/build.bat index ded1cfb5b2d6f6..425558f99d5910 100644 --- a/Tools/msi/build.bat +++ b/Tools/msi/build.bat @@ -48,7 +48,7 @@ if defined BUILDARM64 ( ) if defined BUILDDOC ( - call "%PCBUILD%..\Doc\make.bat" htmlhelp + call "%PCBUILD%..\Doc\make.bat" html if errorlevel 1 exit /B %ERRORLEVEL% ) @@ -87,8 +87,8 @@ echo build.bat [-x86] [-x64] [-arm64] [--doc] [-h] [--test-marker] [--pack] [-r] echo. echo -x86 Build x86 installers echo -x64 Build x64 installers -echo -ARM64 Build ARM64 installers -echo --doc Build CHM documentation +echo -ARM64 Build ARM64 installers +echo --doc Build documentation echo --test-marker Build with test markers echo --no-test-marker Build without test markers (default) echo --pack Embed core MSIs into installer diff --git a/Tools/msi/buildrelease.bat b/Tools/msi/buildrelease.bat index d057ca675363f7..0373c9f7b836a7 100644 --- a/Tools/msi/buildrelease.bat +++ b/Tools/msi/buildrelease.bat @@ -81,7 +81,7 @@ if ERRORLEVEL 1 (echo Cannot locate MSBuild.exe on PATH or as MSBUILD variable & if "%SKIPBUILD%" EQU "1" goto skipdoc if "%SKIPDOC%" EQU "1" goto skipdoc -call "%D%..\..\doc\make.bat" htmlhelp +call "%D%..\..\doc\make.bat" html if errorlevel 1 exit /B %ERRORLEVEL% :skipdoc diff --git a/Tools/msi/bundle/Default.wxl b/Tools/msi/bundle/Default.wxl index 70fb467ec8b193..2eddd1f749ec5a 100644 --- a/Tools/msi/bundle/Default.wxl +++ b/Tools/msi/bundle/Default.wxl @@ -67,7 +67,7 @@ Select Customize to review current options. &Back B&rowse &Documentation - Installs the Python documentation file. + Installs the Python documentation files. &pip Installs pip, which can download and install other Python packages. tcl/tk and &IDLE diff --git a/Tools/msi/common.wxs b/Tools/msi/common.wxs index 4554e80014a290..b819d320ee9481 100644 --- a/Tools/msi/common.wxs +++ b/Tools/msi/common.wxs @@ -85,7 +85,9 @@ - + + + diff --git a/Tools/msi/doc/doc.wixproj b/Tools/msi/doc/doc.wixproj index ea9929acd05ff7..83687968faebea 100644 --- a/Tools/msi/doc/doc.wixproj +++ b/Tools/msi/doc/doc.wixproj @@ -10,21 +10,28 @@ - python$(MajorVersionNumber)$(MinorVersionNumber)$(MicroVersionNumber)$(ReleaseLevelName).chm - false - true - - - $(DefineConstants);DocFilename=$(DocFilename); + $(PySourcePath)Doc\build\html\ + $(DocHtmlPath)\ + + doc_html + - - - + + + $(DocHtmlPath) + !(bindpath.doc_html) + $(DocHtmlPath)..\ + Doc_ + doc_html + + + \ No newline at end of file diff --git a/Tools/msi/doc/doc.wxs b/Tools/msi/doc/doc.wxs index 1d7706bb4d50a0..e80fff43418bb9 100644 --- a/Tools/msi/doc/doc.wxs +++ b/Tools/msi/doc/doc.wxs @@ -8,35 +8,31 @@ - - - - 1 - - - + + + + + + + - + - - - - diff --git a/Tools/msi/doc/doc_files.wxs b/Tools/msi/doc/doc_files.wxs deleted file mode 100644 index fe09afe4d3c76b..00000000000000 --- a/Tools/msi/doc/doc_files.wxs +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - - - - - - diff --git a/Tools/msi/doc/doc_no_files.wxs b/Tools/msi/doc/doc_no_files.wxs deleted file mode 100644 index 7ab7c2690689c7..00000000000000 --- a/Tools/msi/doc/doc_no_files.wxs +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - - - - - diff --git a/Tools/msi/msi.props b/Tools/msi/msi.props index b5fd3d3a3da74b..06aa0b8bbca277 100644 --- a/Tools/msi/msi.props +++ b/Tools/msi/msi.props @@ -115,9 +115,6 @@ - - - src diff --git a/Tools/msi/uploadrelease.ps1 b/Tools/msi/uploadrelease.ps1 index 7c825c443f2287..a8669e5d65ed14 100644 --- a/Tools/msi/uploadrelease.ps1 +++ b/Tools/msi/uploadrelease.ps1 @@ -80,19 +80,19 @@ if (-not $skipupload) { "" if ($doc_htmlhelp) { - pushd $doc_htmlhelp + $chm = gci -EA 0 $doc_htmlhelp\python*.chm, $doc_htmlhelp\python*.chm.asc } else { - pushd $build + $chm = gci -EA 0 $build\python*.chm, $build\python*.chm.asc } - $chm = gci python*.chm, python*.chm.asc - popd $d = "$target/$($p[0])/" & $plink -batch $user@$server mkdir $d & $plink -batch $user@$server chgrp downloads $d & $plink -batch $user@$server chmod o+rx $d - & $pscp -batch $chm.FullName "$user@${server}:$d" - if (-not $?) { throw "Failed to upload $chm" } + if ($chm) { + & $pscp -batch $chm.FullName "$user@${server}:$d" + if (-not $?) { throw "Failed to upload $chm" } + } $dirs = gci "$build" -Directory if ($embed) {