diff --git a/Doc/Makefile b/Doc/Makefile index a2d89343648dc1..9c3e7aca6a7ddb 100644 --- a/Doc/Makefile +++ b/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 diff --git a/Doc/conf.py b/Doc/conf.py index 27cf03d6bea05a..30b2c43a808d6a 100644 --- a/Doc/conf.py +++ b/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', } diff --git a/Doc/download.rst b/Doc/download.rst new file mode 100644 index 00000000000000..91d2e54ddaac33 --- /dev/null +++ b/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/ diff --git a/Doc/tools/extensions/archive_downloads.py b/Doc/tools/extensions/archive_downloads.py new file mode 100644 index 00000000000000..4476f4e23ad666 --- /dev/null +++ b/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, + } diff --git a/Doc/tools/templates/download.html b/Doc/tools/templates/download.html deleted file mode 100644 index 45ec436fee72d7..00000000000000 --- a/Doc/tools/templates/download.html +++ /dev/null @@ -1,75 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Download') %} -{% if daily is defined %} - {% set dl_base = pathto('archives', resource=True) %} - {% set dl_version = version %} -{% else %} - {# - The link below returns HTTP 404 until the first related alpha release. - This is expected; use daily documentation builds for CPython development. - #} - {% set dl_base = 'https://www.python.org/ftp/python/doc/' + release %} - {% set dl_version = release %} -{% endif %} - -{% block body %} -

{% trans %}Download Python {{ dl_version }} Documentation{% endtrans %}

- -{% if last_updated %}

{% trans %}Last updated on: {{ last_updated }}.{% endtrans %}

{% endif %} - -

{% trans %}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.{% endtrans %}

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
{% trans %}Format{% endtrans %}{% trans %}Packed as .zip{% endtrans %}{% trans %}Packed as .tar.bz2{% endtrans %}
{% trans %}PDF{% endtrans %}{% trans download_size="17" %}Download (ca. {{ download_size }} MiB){% endtrans %}{% trans download_size="17" %}Download (ca. {{ download_size }} MiB){% endtrans %}
{% trans %}HTML{% endtrans %}{% trans download_size="13" %}Download (ca. {{ download_size }} MiB){% endtrans %}{% trans download_size="8" %}Download (ca. {{ download_size }} MiB){% endtrans %}
{% trans %}Plain text{% endtrans %}{% trans download_size="4" %}Download (ca. {{ download_size }} MiB){% endtrans %}{% trans download_size="3" %}Download (ca. {{ download_size }} MiB){% endtrans %}
{% trans %}Texinfo{% endtrans %}{% trans download_size="9" %}Download (ca. {{ download_size }} MiB){% endtrans %}{% trans download_size="7" %}Download (ca. {{ download_size }} MiB){% endtrans %}
{% trans %}EPUB{% endtrans %}{% trans download_size="6" %}Download (ca. {{ download_size }} MiB){% endtrans %}
- -

{% trans %}These archives contain all the content in the documentation.{% endtrans %}

- - -

{% trans %}Unpacking{% endtrans %}

- -

{% trans %}Unix users should download the .tar.bz2 archives; these are bzipped tar -archives and can be handled in the usual way using tar and the bzip2 -program. The Info-ZIP unzip program can be -used to handle the ZIP archives if desired. The .tar.bz2 archives provide the -best compression and fastest download times.{% endtrans %}

- -

{% trans %}Windows users can use the ZIP archives since those are customary on that -platform. These are created on Unix using the Info-ZIP zip program.{% endtrans %}

- - -

{% trans %}Problems{% endtrans %}

- -

{% trans %}If you have comments or suggestions for the Python documentation, please send -email to docs@python.org.{% endtrans %}

-{% endblock %} diff --git a/Doc/tools/templates/dummy.html b/Doc/tools/templates/dummy.html index 49c2a71a5e40cf..fe67f5380cf1ee 100644 --- a/Doc/tools/templates/dummy.html +++ b/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 %}