Doc: Convert the download page to reST

Doc/Makefile

@@ -306,12 +306,12 @@ serve:
 # for development releases: always build
 .PHONY: autobuild-dev
 autobuild-dev:
-	$(MAKE) dist SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) dist SPHINXOPTS='$(SPHINXOPTS) -Ea -t=daily'
 
 # for quick rebuilds (HTML only)
 .PHONY: autobuild-dev-html
 autobuild-dev-html:
-	$(MAKE) html SPHINXOPTS='$(SPHINXOPTS) -Ea -A daily=1'
+	$(MAKE) html SPHINXOPTS='$(SPHINXOPTS) -Ea -t=daily'
 
 # for stable releases: only build if not in pre-release stage (alpha, beta)
 # release candidate downloads are okay, since the stable tree can be in that stage

Doc/conf.py

@@ -69,6 +69,7 @@
 version, release = importlib.import_module('patchlevel').get_version_info()
 
 rst_epilog = f"""
+.. |archives_version| replace:: {version if 'daily' in tags else release}
 .. |python_version_literal| replace:: ``Python {version}``
 .. |python_x_dot_y_literal| replace:: ``python{version}``
 .. |usr_local_bin_python_x_dot_y_literal| replace:: ``/usr/local/bin/python{version}``
@@ -378,7 +379,6 @@
 
 # Additional templates that should be rendered to pages.
 html_additional_pages = {
-    'download': 'download.html',
     'index': 'indexcontent.html',
 }
 

Doc/download.rst

@@ -0,0 +1,59 @@
+:orphan:
+
+.. title:: Download
+
+************************************************
+Download Python |archives_version| Documentation
+************************************************
+
+**Last updated on:** |last_updated|
+
+.. |last_updated| date:: %b %d, %Y (%H:%M)
+
+To download an archive containing all the documents for this version of
+Python in one of various formats, follow one of links in this table.
+
+.. list-table::
+   :align: left
+   :header-rows: 1
+
+   * - Format
+     - Packed as .zip
+     - Packed as .tar.bz2
+
+   * - PDF
+     - :download-archive:`python-$VERSION-docs-pdf-a4.zip` (c. 17 MiB)
+     - :download-archive:`python-$VERSION-docs-pdf-a4.tar.bz2` (c. 17 MiB)
+
+   * - HTML
+     - :download-archive:`python-$VERSION-docs-html.zip` (c. 13 MiB)
+     - :download-archive:`python-$VERSION-docs-html.tar.bz2` (c. 8 MiB)
+
+   * - Plain text
+     - :download-archive:`python-$VERSION-docs-text.zip` (c. 4 MiB)
+     - :download-archive:`python-$VERSION-docs-text.tar.bz2` (c. 3 MiB)
+
+   * - Texinfo
+     - :download-archive:`python-$VERSION-docs-texinfo.zip` (c. 9 MiB)
+     - :download-archive:`python-$VERSION-docs-texinfo.tar.bz2` (c. 7 MiB)
+
+   * - EPUB
+     - :download-archive:`python-$VERSION-docs.epub` (c. 6 MiB)
+     -
+
+These archives contain all the content in the documentation.
+
+
+Unpacking
+=========
+
+Unix users should download the ``.tar.bz2`` archives;
+these are bzipped tar archives and can be handled in the usual way
+using the :program:`tar` and :program:`bzip2` programmes.
+:program:`unzip` from `Info-ZIP`_ can be used with the ZIP archives if desired.
+The `.tar.bz2` archives provide the best compression and download times.
+
+Windows users can use the ZIP archives,
+which are created on Unix using :program:`zip` from `Info-ZIP`_.
+
+.. _Info-ZIP: https://infozip.sourceforge.net/

Doc/tools/extensions/pyspecific.py

@@ -83,6 +83,29 @@ def gh_issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
     return [refnode], []
 
 
+# Support for variable archive download links
+
+def download_archive_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
+    env = inliner.document.settings.env
+    config = env.config
+    tags = env.app.tags
+    if 'daily' in tags and 'format_html' in tags:
+        dl_base = 'archives/'
+        dl_version = config.version
+    else:
+        dl_base = 'https://www.python.org/ftp/python/doc/'
+        dl_version = config.release
+    uri = dl_base + unescape(text).replace('$VERSION', dl_version)
+    refnode = nodes.reference('Download', 'Download', refuri=uri)
+    return [refnode], []
+
+
+def download_only_html(app):
+    """Don't create the download page for non-HTML builders."""
+    if 'format_html' not in app.tags:
+        app.config.exclude_patterns.append('download.rst')
+
+
 # Support for marking up implementation details
 
 class ImplementationDetail(SphinxDirective):
@@ -488,6 +511,7 @@ def patch_pairindextypes(app, _env) -> None:
 def setup(app):
     app.add_role('issue', issue_role)
     app.add_role('gh', gh_issue_role)
+    app.add_role('download-archive', download_archive_role)
     app.add_directive('impl-detail', ImplementationDetail)
     app.add_directive('availability', Availability)
     app.add_directive('versionadded', PyVersionChange, override=True)
@@ -507,5 +531,6 @@ def setup(app):
     app.add_directive_to_domain('py', 'awaitablemethod', PyAwaitableMethod)
     app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
     app.add_directive('miscnews', MiscNews)
+    app.connect('builder-inited', download_only_html)
     app.connect('env-check-consistency', patch_pairindextypes)
     return {'version': '1.0', 'parallel_read_safe': True}