From 9b1fce0fc79b0a30914d92eed4e62587a58d1c0c Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Thu, 26 Sep 2024 16:56:39 +0100 Subject: [PATCH] Doc: Convert the download page to reST --- Doc/Makefile | 4 +- Doc/conf.py | 2 +- Doc/download.rst | 59 +++++++++++++++++++++++ Doc/tools/extensions/pyspecific.py | 25 ++++++++++ Doc/tools/templates/download.html | 75 ------------------------------ 5 files changed, 87 insertions(+), 78 deletions(-) create mode 100644 Doc/download.rst delete mode 100644 Doc/tools/templates/download.html 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..cbe6802e576373 100644 --- a/Doc/conf.py +++ b/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', } diff --git a/Doc/download.rst b/Doc/download.rst new file mode 100644 index 00000000000000..eb68cc579cb3e8 --- /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/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 1f725c2377035b..04bcf5bdfedac0 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/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} 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 %}