Skip to content

Commit 3751b6b

Browse files
zoobazooba
authored
bpo-47086: Remove .chm from Windows installer and add HTML docs (GH-32038)
1 parent 19058b9 commit 3751b6b

19 files changed

+79
-105
lines changed

‎.azure-pipelines/windows-release.yml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,13 +43,17 @@ parameters:
4343
# Eventually when we stop releasing anything that old, we can drop this
4444
# argument (and make it implicitly always 'true')
4545
- name: ARM64TclTk
46-
displayName: "Use Tcl/Tk for ARM64"
46+
displayName: "Use Tcl/Tk for ARM64 (3.11 and later)"
4747
type: boolean
4848
default: true
4949
- name: DoPGO
5050
displayName: "Run PGO"
5151
type: boolean
5252
default: true
53+
- name: DoCHM
54+
displayName: "Produce compiled help document (pre-3.11)"
55+
type: boolean
56+
default: false
5357
- name: DoLayout
5458
displayName: "Produce full layout artifact"
5559
type: boolean
@@ -86,6 +90,7 @@ variables:
8690
${{ if ne(parameters.SigningCertificate, 'Unsigned') }}:
8791
SigningCertificate: ${{ parameters.SigningCertificate }}
8892
SigningDescription: ${{ parameters.SigningDescription }}
93+
DoCHM: ${{ parameters.DoCHM }}
8994
DoLayout: ${{ parameters.DoLayout }}
9095
DoMSIX: ${{ parameters.DoMSIX }}
9196
DoNuget: ${{ parameters.DoNuget }}

‎.azure-pipelines/windows-release/gpg-sign.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,14 @@ parameters:
33
GPGPassphrase: $(GPGPassphrase)
44
Files: '*'
55
WorkingDirectory: $(Build.BinariesDirectory)
6+
Condition: succeeded()
67

78
steps:
89
- task: DownloadSecureFile@1
910
name: gpgkey
1011
inputs:
1112
secureFile: ${{ parameters.GPGKeyFile }}
13+
condition: ${{ parameters.Condition }}
1214
displayName: 'Download GPG key'
1315

1416
- powershell: |
@@ -18,6 +20,7 @@ steps:
1820
gpg/gpg2.exe -ba --batch --passphrase ${{ parameters.GPGPassphrase }} $_
1921
"Made signature for $_"
2022
}
23+
condition: ${{ parameters.Condition }}
2124
displayName: 'Generate GPG signatures'
2225
workingDirectory: ${{ parameters.WorkingDirectory }}
2326

‎.azure-pipelines/windows-release/msi-steps.yml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,6 @@ steps:
2121
inputs:
2222
sourceFolder: $(Build.BinariesDirectory)\doc
2323
targetFolder: $(Build.SourcesDirectory)\Doc\build
24-
contents: |
25-
htmlhelp\*.chm
2624

2725
- task: DownloadPipelineArtifact@1
2826
displayName: 'Download artifact: bin_win32'

‎.azure-pipelines/windows-release/stage-build.yml

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@ jobs:
55
- job: Build_Docs
66
displayName: Docs build
77
pool:
8-
#name: 'Windows Release'
98
vmImage: windows-2022
109

1110
workspace:
@@ -21,14 +20,10 @@ jobs:
2120

2221
- script: Doc\make.bat htmlhelp
2322
displayName: 'Build CHM docs'
23+
condition: and(succeeded(), eq(variables['DoCHM'], 'true'))
2424
env:
2525
BUILDDIR: $(Build.BinariesDirectory)\Doc
2626

27-
#- powershell: |
28-
# mkdir -Force "$(Build.BinariesDirectory)\Doc\htmlhelp"
29-
# iwr "https://www.python.org/ftp/python/3.8.0/python380.chm" -OutFile "$(Build.BinariesDirectory)\Doc\htmlhelp\python390a0.chm"
30-
# displayName: 'Cheat at building CHM docs'
31-
3227
- task: CopyFiles@2
3328
displayName: 'Assemble artifact: Doc'
3429
inputs:
@@ -44,6 +39,7 @@ jobs:
4439
targetPath: $(Build.ArtifactStagingDirectory)\Doc
4540
artifactName: doc
4641

42+
4743
- job: Build_Python
4844
displayName: Python build
4945

‎.azure-pipelines/windows-release/stage-publish-pythonorg.yml

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,13 @@ jobs:
8787
- template: ./gpg-sign.yml
8888
parameters:
8989
GPGKeyFile: 'python-signing.key'
90-
Files: 'doc\htmlhelp\*.chm, msi\*\*, embed\*.zip'
90+
Files: 'msi\*\*, embed\*.zip'
91+
92+
- template: ./gpg-sign.yml
93+
parameters:
94+
GPGKeyFile: 'python-signing.key'
95+
Files: 'doc\htmlhelp\*.chm'
96+
Condition: and(succeeded(), eq(variables['DoCHM'], 'true'))
9197

9298
- powershell: >
9399
$(Build.SourcesDirectory)\Tools\msi\uploadrelease.ps1

‎Misc/NEWS.d/next/Windows/2022-03-21-20-45-01.bpo-47086.bIuKlF.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
The installer for Windows now includes documentation as loose HTML files
2+
rather than a single compiled :file:`.chm` file.

‎PC/layout/support/filesets.py

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ def _return_true(f):
9393

9494

9595
def rglob(root, patterns, condition=None):
96+
if not os.path.isdir(root):
97+
return
9698
if isinstance(patterns, tuple):
9799
for p in patterns:
98100
yield from _rglob(root, p, condition or _return_true)

‎PC/layout/support/options.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ def public(f):
8080
"venv",
8181
"dev",
8282
"symbols",
83-
"chm",
83+
"html-doc",
8484
],
8585
},
8686
"embed": {

‎Tools/msi/README.txt

Lines changed: 16 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,16 @@ Quick Build Info
44
For testing, the installer should be built with the Tools/msi/build.bat
55
script:
66

7-
build.bat [-x86] [-x64] [--doc]
7+
build.bat [-x86] [-x64] [-ARM64] [--doc]
88

99
For an official release, the installer should be built with the
1010
Tools/msi/buildrelease.bat script and environment variables:
1111

12-
set PYTHON=<path to Python 2.7 or 3.4>
12+
set PYTHON=<path to Python 3.8 or later>
1313
set SPHINXBUILD=<path to sphinx-build.exe>
14-
set PATH=<path to Git (git.exe)>;
15-
<path to HTML Help Compiler (hhc.exe)>;%PATH%
14+
set PATH=<path to Git (git.exe)>;%PATH%
1615

17-
buildrelease.bat [-x86] [-x64] [-D] [-B]
16+
buildrelease.bat [-x86] [-x64] [-ARM64] [-D] [-B]
1817
[-o <output directory>] [-c <certificate name>]
1918

2019
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
7776
For testing, the installer should be built with the Tools/msi/build.bat
7877
script:
7978

80-
build.bat [-x86] [-x64] [--doc] [--test-marker] [--pack]
79+
build.bat [-x86] [-x64] [-ARM64] [--doc] [--test-marker] [--pack]
8180

8281
This script will build the required configurations of Python and
8382
generate an installer layout in PCbuild/(win32|amd64)/en-us.
8483

85-
Specify -x86 and/or -x64 to build for each platform. If neither is
86-
specified, both platforms will be built. Currently, both the debug and
84+
Specify -x86, -x64 and/or -ARM64 to build for each platform. If none are
85+
specified, both x64 and x86 will be built. Currently, both the debug and
8786
release versions of Python are required for the installer.
8887

89-
Specify --doc to build the documentation (.chm) file. If the file is not
90-
available, it will simply be excluded from the installer. Ensure
91-
%PYTHON% and %SPHINXBUILD% are set when passing this option. You may
92-
also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC on
93-
your PATH or in externals/.
88+
Specify --doc to include the documentation files. Ensure %PYTHON% and
89+
%SPHINXBUILD% are set when passing this option.
9490

9591
Specify --test-marker to build an installer that works side-by-side with
9692
an official Python release. All registry keys and install locations will
@@ -106,18 +102,18 @@ Tools/msi/buildrelease.bat script:
106102

107103
set PYTHON=<path to Python 2.7 or 3.4>
108104
set SPHINXBUILD=<path to sphinx-build.exe>
109-
set PATH=<path to Git (git.exe)>;
110-
<path to HTML Help Compiler (hhc.exe)>;%PATH%
105+
set PATH=<path to Git (git.exe)>;%PATH%
111106

112-
buildrelease.bat [-x86] [-x64] [-D] [-B]
107+
buildrelease.bat [-x86] [-x64] [-ARM64] [-D] [-B]
113108
[-o <output directory>] [-c <certificate name>]
114109

115-
Specify -x86 and/or -x64 to build for each platform. If neither is
116-
specified, both platforms will be built. Currently, both the debug and
110+
Specify -x86, -x64 and/or -ARM64 to build for each platform. If none are
111+
specified, both x64 and x86 will be built. Currently, both the debug and
117112
release versions of Python are required for the installer.
118113

119114
Specify -D to skip rebuilding the documentation. The documentation is
120115
required for a release and the build will fail if it is not available.
116+
Ensure %PYTHON% and %SPHINXBUILD% are set if you omit this option.
121117

122118
Specify -B to skip rebuilding Python. This is useful to only rebuild the
123119
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
129125
signable binaries in Python as well as each file making up the
130126
installer. Official releases of Python must be signed.
131127

132-
Ensure %PYTHON% and %SPHINXBUILD% are set when passing this option. You
133-
may also set %HTMLHELP% to the Html Help Compiler (hhc.exe), or put HHC
134-
on your PATH or in externals/. You will also need Git (git.exe) on
135-
your PATH.
136128

137129
If WiX is not found on your system, it will be automatically downloaded
138130
and extracted to the externals/ directory.
@@ -366,7 +358,7 @@ Within this install directory is the following approximate layout:
366358
.\python3x.dll The core interpreter
367359
.\python3.dll The stable ABI reference
368360
.\DLLs Stdlib extensions (*.pyd) and dependencies
369-
.\Doc Documentation (*.chm)
361+
.\Doc Documentation (*.html)
370362
.\include Development headers (*.h)
371363
.\Lib Standard library
372364
.\Lib\test Test suite
@@ -421,7 +413,7 @@ a semicolon.
421413

422414
When the documentation is installed, a key "Help" is created within the
423415
root key, with a subkey "Main Python Documentation" with its default
424-
value set to the full path to the installed CHM file.
416+
value set to the full path to the main index.html file.
425417

426418

427419
The py.exe launcher is installed as part of a regular Python install,

‎Tools/msi/build.bat

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ if defined BUILDARM64 (
4848
)
4949

5050
if defined BUILDDOC (
51-
call "%PCBUILD%..\Doc\make.bat" htmlhelp
51+
call "%PCBUILD%..\Doc\make.bat" html
5252
if errorlevel 1 exit /B %ERRORLEVEL%
5353
)
5454

@@ -87,8 +87,8 @@ echo build.bat [-x86] [-x64] [-arm64] [--doc] [-h] [--test-marker] [--pack] [-r]
8787
echo.
8888
echo -x86 Build x86 installers
8989
echo -x64 Build x64 installers
90-
echo -ARM64 Build ARM64 installers
91-
echo --doc Build CHM documentation
90+
echo -ARM64 Build ARM64 installers
91+
echo --doc Build documentation
9292
echo --test-marker Build with test markers
9393
echo --no-test-marker Build without test markers (default)
9494
echo --pack Embed core MSIs into installer

‎Tools/msi/buildrelease.bat

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ if ERRORLEVEL 1 (echo Cannot locate MSBuild.exe on PATH or as MSBUILD variable &
8181
if "%SKIPBUILD%" EQU "1" goto skipdoc
8282
if "%SKIPDOC%" EQU "1" goto skipdoc
8383

84-
call "%D%..\..\doc\make.bat" htmlhelp
84+
call "%D%..\..\doc\make.bat" html
8585
if errorlevel 1 exit /B %ERRORLEVEL%
8686
:skipdoc
8787

‎Tools/msi/bundle/Default.wxl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ Select Customize to review current options.</String>
6767
<String Id="CustomBackButton">&amp;Back</String>
6868
<String Id="CustomBrowseButton">B&amp;rowse</String>
6969
<String Id="Include_docLabel">&amp;Documentation</String>
70-
<String Id="Include_docHelpLabel">Installs the Python documentation file.</String>
70+
<String Id="Include_docHelpLabel">Installs the Python documentation files.</String>
7171
<String Id="Include_pipLabel">&amp;pip</String>
7272
<String Id="Include_pipHelpLabel">Installs pip, which can download and install other Python packages.</String>
7373
<String Id="Include_tcltkLabel">tcl/tk and &amp;IDLE</String>

‎Tools/msi/common.wxs

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,9 @@
8585

8686
<Fragment>
8787
<DirectoryRef Id="InstallDirectory">
88-
<Directory Id="Doc" Name="Doc" />
88+
<Directory Id="Doc" Name="Doc">
89+
<Directory Id="Doc_html" Name="html" />
90+
</Directory>
8991
</DirectoryRef>
9092
</Fragment>
9193

‎Tools/msi/doc/doc.wixproj

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -10,21 +10,28 @@
1010
</PropertyGroup>
1111
<Import Project="..\msi.props" />
1212
<PropertyGroup>
13-
<DocFilename>python$(MajorVersionNumber)$(MinorVersionNumber)$(MicroVersionNumber)$(ReleaseLevelName).chm</DocFilename>
14-
<IncludeDocFile>false</IncludeDocFile>
15-
<IncludeDocFile Condition="$(BuildForRelease) or Exists('$(PySourcePath)Doc\build\htmlhelp\$(DocFilename)')">true</IncludeDocFile>
16-
</PropertyGroup>
17-
<PropertyGroup Condition="$(IncludeDocFile)">
18-
<DefineConstants>$(DefineConstants);DocFilename=$(DocFilename);</DefineConstants>
13+
<DocHtmlPath>$(PySourcePath)Doc\build\html\</DocHtmlPath>
14+
<DocHtmlPath Condition="!HasTrailingSlash($(DocHtmlPath))">$(DocHtmlPath)\</DocHtmlPath>
1915
</PropertyGroup>
2016
<ItemGroup>
17+
<LinkerBindInputPaths Include="$(DocHtmlPath)">
18+
<BindName>doc_html</BindName>
19+
</LinkerBindInputPaths>
2120
<Compile Include="doc.wxs" />
22-
<Compile Include="doc_files.wxs" Condition="$(IncludeDocFile)" />
23-
<Compile Include="doc_no_files.wxs" Condition="!$(IncludeDocFile)" />
2421
</ItemGroup>
2522
<ItemGroup>
2623
<WxlTemplate Include="*.wxl_template" />
2724
</ItemGroup>
28-
25+
<ItemGroup>
26+
<InstallFiles Include="$(DocHtmlPath)**\*"
27+
Exclude="$(DocHtmlPath)_sources\**\*">
28+
<SourceBase>$(DocHtmlPath)</SourceBase>
29+
<Source>!(bindpath.doc_html)</Source>
30+
<TargetBase>$(DocHtmlPath)..\</TargetBase>
31+
<Target_>Doc_</Target_>
32+
<Group>doc_html</Group>
33+
</InstallFiles>
34+
</ItemGroup>
35+
2936
<Import Project="..\msi.targets" />
3037
</Project>

‎Tools/msi/doc/doc.wxs

Lines changed: 10 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,35 +8,31 @@
88
<PropertyRef Id="UpgradeTable" />
99
<PropertyRef Id="REGISTRYKEY" />
1010

11-
<Property Id="HHExe" Value="C:\Windows\hh.exe" />
12-
<CustomAction Id="SetHHExe" Property="HHExe" Value='[WindowsFolder]\hh.exe' Execute="immediate" />
13-
<InstallExecuteSequence>
14-
<Custom Action="SetHHExe" Before="CostFinalize">1</Custom>
15-
</InstallExecuteSequence>
16-
1711
<Feature Id="DefaultFeature" AllowAdvertise="no" Title="!(loc.Title)" Description="!(loc.Description)">
18-
<ComponentGroupRef Id="doc" Primary="yes" />
12+
<ComponentGroupRef Id="doc_html" Primary="yes" />
1913
<ComponentRef Id="OptionalFeature" />
14+
15+
<Component Id="doc_reg" Directory="Doc" Guid="*">
16+
<RegistryKey Root="HKMU" Key="[REGISTRYKEY]">
17+
<RegistryValue Key="Help\Main Python Documentation" Type="string" Value="[#Doc_html_index.html]" KeyPath="yes" />
18+
</RegistryKey>
19+
</Component>
2020
</Feature>
2121
<Feature Id="Shortcuts" AllowAdvertise="no" Title="!(loc.Title)" Description="!(loc.Description)">
22-
<ComponentGroupRef Id="doc" />
22+
<ComponentGroupRef Id="doc_html" />
2323

24-
<?ifdef DocFilename ?>
2524
<Component Id="doc_shortcut" Directory="MenuDir" Guid="*">
2625
<RegistryKey Root="HKMU" Key="[OPTIONALFEATURESREGISTRYKEY]">
2726
<RegistryValue Name="$(var.OptionalFeatureName)_shortcut" Type="string" Value="$(var.Version)" KeyPath="yes" />
2827
</RegistryKey>
29-
<Shortcut Id="python.chm"
30-
Target="[HHExe]"
31-
Arguments="[#python.chm]"
28+
<Shortcut Id="python.html"
29+
Target="[#Doc_html_index.html]"
3230
Name="!(loc.ShortcutName)"
3331
Description="!(loc.ShortcutDescription)"
3432
WorkingDirectory="InstallDirectory"
3533
Show="maximized" />
3634
<RemoveFolder Id="Remove_MenuDir" On="uninstall" />
3735
</Component>
38-
<?endif ?>
39-
4036
</Feature>
4137
</Product>
4238
</Wix>

‎Tools/msi/doc/doc_files.wxs

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎Tools/msi/doc/doc_no_files.wxs

Lines changed: 0 additions & 17 deletions
This file was deleted.

0 commit comments

Comments
 (0)