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

@@ -20,6 +20,7 @@
 # ---------------------
 
 extensions = [
+    'archive_downloads',
     'audit_events',
     'c_annotations',
     'glossary_search',
@@ -69,10 +70,11 @@
 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}``
-"""
+"""  # noqa: F821
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -378,7 +380,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/archive_downloads.py

@@ -0,0 +1,62 @@
+"""Support for the download page.
+
+When the documentation is built and served from the docs server,
+we prefer to link to the `up-to-date archives`_ instead of the
+static releases on the python.org FTP site.
+In an attempt to reduce confusion about these archives,
+we re-title the page with the short version (major.minor)
+instead of a full release version.
+
+Contents:
+
+* The ``:download-archive:`` role implements variable download links.
+* The ``download_only_html()`` function prevents building the download
+  page on non-HTML builders.
+
+.. _up-to-date archives: https://docs.python.org/3/archives/
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from docutils import nodes
+from sphinx.locale import _ as sphinx_gettext
+from sphinx.util.docutils import SphinxRole
+
+if TYPE_CHECKING:
+    from docutils.nodes import Node, system_message
+    from sphinx.application import Sphinx
+    from sphinx.util.typing import ExtensionMetadata
+
+
+class DownloadArchiveRole(SphinxRole):
+    def run(self) -> tuple[list[Node], list[system_message]]:
+        tags = self.env.app.tags
+        if "daily" in tags and "format_html" in tags:
+            dl_base = "archives/"
+            dl_version = self.config.version
+        else:
+            dl_base = "https://www.python.org/ftp/python/doc/"
+            dl_version = self.config.release
+
+        ref_text = sphinx_gettext("Download")
+        uri = dl_base + self.text.replace("$VERSION", dl_version)
+        refnode = nodes.reference("Download", ref_text, refuri=uri)
+        return [refnode], []
+
+
+def download_only_html(app: Sphinx) -> None:
+    """Don't create the download page for non-HTML builders."""
+    if "format_html" not in app.tags:
+        app.config.exclude_patterns.append("download.rst")
+
+
+def setup(app: Sphinx) -> ExtensionMetadata:
+    app.add_role("download-archive", DownloadArchiveRole())
+    app.connect("builder-inited", download_only_html)
+    return {
+        "version": "1.0",
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

Doc/tools/templates/dummy.html

@@ -1,6 +1,10 @@
 This file is not an actual template, but used to add some
 texts in extensions to sphinx.pot file.
 
+In extensions/archive_downloads.py:
+
+{% trans %}Download{% endtrans %}
+
 In extensions/pyspecific.py:
 
 {% trans %}CPython implementation detail:{% endtrans %}