Various doc fixes. (#2686)

+ Upgrade pagefind to 1.3.0 and enable search result highlighting.
+ Fix Deploy Doc Site workflow to work for search in forks.
+ Fix various re-directs pointed out via `--linkcheck` to point to the 
  new homes.

Author: jsirois

.github/workflows/doc-site.yml

@@ -34,8 +34,14 @@ jobs:
           python-version: "3.11"
       - name: Build Doc Site
         uses: pex-tool/actions/run-tox@c53dadd8b410bbd66480de91067e9e45d2b3af38
+        if: github.repository_owner == 'pex-tool'
         with:
           tox-env: docs -- --linkcheck --pdf --clean-html
+      - name: Build Fork Doc Site
+        uses: pex-tool/actions/run-tox@c53dadd8b410bbd66480de91067e9e45d2b3af38
+        if: github.repository_owner != 'pex-tool'
+        with:
+          tox-env: docs -- --linkcheck --pdf --clean-html --subdir ${{ github.event.repository.name }}
       - name: Setup Pages
         uses: actions/configure-pages@v4
       - name: Upload artifact

CHANGES.md

@@ -1855,7 +1855,7 @@ Pex version range.
 
 This is another hotfix release for 2.1.68 that fixes a bug in `*.data/*`
 file handling for installed wheels which is outlined in [PEP
-427](https://www.python.org/dev/peps/pep-0427/#installing-a-wheel-distribution-1-0-py32-none-any-whl)
+427](https://peps.python.org/pep-0427/#installing-a-wheel-distribution-1-0-py32-none-any-whl)
 
 * Handle `*.data/*` RECORD entries not existing. (#1644)
 

README.rst

@@ -24,7 +24,7 @@ PEX
 Overview
 ========
 pex is a library for generating .pex (Python EXecutable) files which are
-executable Python environments in the spirit of `virtualenvs <http://virtualenv.org>`_.
+executable Python environments in the spirit of `virtualenvs <https://virtualenv.pypa.io>`_.
 pex is an expansion upon the ideas outlined in
 `PEP 441 <https://peps.python.org/pep-0441/>`_
 and makes the deployment of Python applications as simple as ``cp``.  pex files may even
@@ -36,7 +36,7 @@ pex files can be built using the ``pex`` tool.  Build systems such as `Pants
 support building .pex files directly.
 
 Still unsure about what pex does or how it works?  Watch this quick lightning
-talk: `WTF is PEX? <http://www.youtube.com/watch?v=NmpnGhRwsu0>`_.
+talk: `WTF is PEX? <https://www.youtube.com/watch?v=NmpnGhRwsu0>`_.
 
 pex is licensed under the Apache2 license.
 

docs/_templates/page.html

@@ -0,0 +1,9 @@
+{% extends "!page.html" %}
+
+{% block scripts -%}
+{{ super() }}
+<script type="module">
+    await import('{{ pex_site_subdir | default() }}/_pagefind/pagefind-highlight.js');
+    new PagefindHighlight({ highlightParam: "highlight" });
+</script>
+{%- endblock scripts %}

docs/_templates/search.html

@@ -1,4 +1,4 @@
-{% extends "page.html" %}
+{% extends "!page.html" %}
 
 {%- block htmltitle -%}
 <title>{{ _("Search") }} - {{ docstitle }}</title>
@@ -11,11 +11,12 @@ <h1>{{ _("Search") }}</h1>
 
 {% block scripts -%}
 {{ super() }}
-<script src="/_pagefind/pagefind-ui.js" type="text/javascript"></script>
+<script src="{{ pex_site_subdir | default() }}/_pagefind/pagefind-ui.js" type="text/javascript"></script>
 <script>
   window.addEventListener("DOMContentLoaded", () => {
     new PagefindUI({
       element: "#search",
+      highlightParam: "highlight",
       showSubResults: true,
     });
 

docs/buildingpex.rst

@@ -396,7 +396,7 @@ string (e.g., ``3.6`` or ``3.10.1``) and ``ABI`` is the ABI tag (e.g., ``cp36m``
 ``abi3``, ``none``). A complete example: ``linux_x86_64-cp-36-cp36m``.
 
 **Constraints**: when ``--platform`` is used the
-`environment marker <https://www.python.org/dev/peps/pep-0508/#environment-markers>`_
+`environment marker <https://peps.python.org/pep-0508/#environment-markers>`_
 ``python_full_version`` will not be available if ``PYVER`` is not given as a three component dotted
 version since ``python_full_version`` is meant to have 3 digits (e.g., ``3.8.10``). If a
 ``python_full_version`` environment marker is encountered during a resolve, an
@@ -414,11 +414,11 @@ The complete platform can be either a path to a file containing JSON data or els
 literal. In either case, the JSON object is expected to have two fields with any other fields
 ignored. The ``marker_environment`` field should have an object value with string field values
 corresponding to
-`PEP-508 marker environment <https://www.python.org/dev/peps/pep-0508/#environment-markers>`_
+`PEP-508 marker environment <https://peps.python.org/pep-0508/#environment-markers>`_
 entries. It is OK to only have a subset of valid marker environment fields but it is not valid to
 present entries not defined in PEP-508. The ``compatible_tags`` field should have an array of
 strings value containing the compatible tags in order from most specific first to least
-specific last as defined in `PEP-425 <https://www.python.org/dev/peps/pep-0425>`_. Pex can create
+specific last as defined in `PEP-425 <https://peps.python.org/pep-0425>`_. Pex can create
 complete platform JSON for you by running it on the target platform like so:
 ``pex3 interpreter inspect --markers --tags``. For more options, particularly to select the desired
 target interpreter see: ``pex3 interpreter inspect --help``.

docs/index.rst

@@ -2,7 +2,7 @@
 pex
 ***
 This project is the home of the .pex file, and the ``pex`` tool which can create them.
-``pex`` also provides a general purpose Python environment-virtualization solution similar to `virtualenv <http://virtualenv.org>`_.
+``pex`` also provides a general purpose Python environment-virtualization solution similar to `virtualenv <https://virtualenv.pypa.io>`_.
 pex is short for "Python Executable"
 
 in brief
@@ -13,15 +13,15 @@ New to python packaging?  Check out `packaging.python.org <https://packaging.pyt
 intro & history
 ===============
 pex contains the Python packaging and distribution libraries originally available through the
-`twitter commons <https://github.com/twitter/commons>`_ but since split out into a separate project.
+`twitter commons <https://github.com/twitter-archive/commons>`_ but since split out into a separate project.
 The most notable components of pex are the .pex (Python EXecutable) format and the
 associated ``pex`` tool which provide a general purpose Python environment virtualization
-solution similar in spirit to `virtualenv <http://virtualenv.org>`_.  PEX files have been used by Twitter to deploy Python applications to production since 2011.
+solution similar in spirit to `virtualenv <https://virtualenv.pypa.io>`_.  PEX files have been used by Twitter to deploy Python applications to production since 2011.
 
 To learn more about what the .pex format is and why it could be useful for
 you, see :ref:`whatispex`  For the impatient, there is also a (slightly outdated) lightning
 talk published by Twitter University: `WTF is PEX?
-<http://www.youtube.com/watch?v=NmpnGhRwsu0>`_.
+<https://www.youtube.com/watch?v=NmpnGhRwsu0>`_.
 To go straight to building pex files, see :ref:`buildingpex`.
 
 Guide:

docs/recipes.rst

@@ -100,7 +100,7 @@ The Pex ``venv`` tool will:
 2) Pre-compile all PEX Python code installed in the venv.
 
 Notably, the PEX venv install is done using a
-`multi-stage build <https://docs.docker.com/develop/develop-images/multistage-build/>`_ to ensure
+`multi-stage build <https://docs.docker.com/build/building/multi-stage/>`_ to ensure
 only the final venv remains on disk and it uses two layers to ensure changes to application code
 do not lead to re-builds of lower layers. This accommodates the common case of modifying and
 re-deploying first party code more often than third party dependencies.
@@ -167,4 +167,4 @@ While building pex files, you may need to fetch dependencies through a proxy. Th
 
     $ pex -v pex
 
-For more information on the requests module support for proxies via environment variables, see the official documentation here: http://docs.python-requests.org/en/master/user/advanced/#proxies.
+For more information on the requests module support for proxies via environment variables, see the official documentation here: https://docs.python-requests.org/en/latest/user/advanced/#proxies.

pex/dist_metadata.py

@@ -469,19 +469,19 @@ def from_filename(cls, path):
         # Handle wheels:
         #
         # The wheel filename convention is specified here:
-        #   https://www.python.org/dev/peps/pep-0427/#file-name-convention.
+        #   https://peps.python.org/pep-0427/#file-name-convention.
         if is_wheel(path):
             project_name, version, _ = os.path.basename(path).split("-", 2)
             return cls(project_name=project_name, version=version)
 
         # Handle sdists:
         #
         # The sdist name format has no accepted specification yet, but there is a proposal here:
-        #   https://www.python.org/dev/peps/pep-0625/#specification.
+        #   https://peps.python.org/pep-0625/#specification.
         #
         # We do the best we can to support the current landscape. A version number can technically
         # contain a dash though, even under the standards, in un-normalized form:
-        #   https://www.python.org/dev/peps/pep-0440/#pre-release-separators.
+        #   https://peps.python.org/pep-0440/#pre-release-separators.
         # For those cases this logic will produce incorrect results and it does not seem there is
         # much we can do since both project names and versions can contain both alphanumeric
         # characters and dashes.
@@ -551,7 +551,7 @@ def requires_python(location):
     # type: (Union[Distribution, MetadataFiles, Text]) -> Optional[SpecifierSet]
     """Examines dist for `Python-Requires` metadata and returns version constraints if any.
 
-    See: https://www.python.org/dev/peps/pep-0345/#requires-python
+    See: https://peps.python.org/pep-0345/#requires-python
 
     :param location: A distribution to check for `Python-Requires` metadata.
     :return: The required python version specifiers.
@@ -624,8 +624,8 @@ def requires_dists(location):
     comes in.
 
     See:
-    + https://www.python.org/dev/peps/pep-0345/#requires-dist-multiple-use
-    + https://www.python.org/dev/peps/pep-0314/#requires-multiple-use
+    + https://peps.python.org/pep-0345/#requires-dist-multiple-use
+    + https://peps.python.org/pep-0314/#requires-multiple-use
 
     :param location: A distribution to check for requirement metadata.
     :return: All requirements found.
@@ -719,7 +719,7 @@ def requires_dists(location):
 class RequirementParseError(Exception):
     """Indicates and invalid requirement string.
 
-    See PEP-508: https://www.python.org/dev/peps/pep-0508
+    See PEP-508: https://peps.python.org/pep-0508
     """
 
     error = attr.ib()  # type: Any

pex/interpreter.py

@@ -304,7 +304,7 @@ def get(cls, binary=None):
                 # Old virtualenv (16 series and lower) sets `sys.real_prefix` in all cases.
                 cast("Optional[str]", getattr(sys, "real_prefix", None))
                 # Both pyvenv and virtualenv 20+ set `sys.base_prefix` as per
-                # https://www.python.org/dev/peps/pep-0405/.
+                # https://peps.python.org/pep-0405/.
                 or cast(str, getattr(sys, "base_prefix", sys.prefix))
             ),
             sys_path=sys_path,
@@ -674,7 +674,7 @@ def __hash__(self):
 class PyVenvCfg(object):
     """Represents a pyvenv.cfg file.
 
-    See: https://www.python.org/dev/peps/pep-0405/#specification
+    See: https://peps.python.org/pep-0405/#specification
     """
 
     class Error(ValueError):
@@ -688,7 +688,7 @@ def parse(cls, path):
         :param path: The path of putative pyvenv.cfg file.
         :raises: :class:`PyVenvCfg.Error` if the given `path` doesn't contain a pyvenv.cfg home key.
         """
-        # See: https://www.python.org/dev/peps/pep-0405/#specification
+        # See: https://peps.python.org/pep-0405/#specification
         config = {}
         with open(path) as fp:
             for line in fp:
@@ -703,7 +703,7 @@ def parse(cls, path):
     @classmethod
     def _get_pyvenv_cfg(cls, path):
         # type: (str) -> Optional[PyVenvCfg]
-        # See: https://www.python.org/dev/peps/pep-0405/#specification
+        # See: https://peps.python.org/pep-0405/#specification
         pyvenv_cfg_path = os.path.join(path, "pyvenv.cfg")
         if os.path.isfile(pyvenv_cfg_path):
             try:
@@ -734,7 +734,7 @@ def find(cls, python_binary):
         #
         # In practice, we see layout 2 in the wild, but layout 1 is also allowed by the spec.
         #
-        # See: # See: https://www.python.org/dev/peps/pep-0405/#specification
+        # See: # See: https://peps.python.org/pep-0405/#specification
         maybe_venv_bin_dir = os.path.dirname(python_binary)
         pyvenv_cfg = cls._get_pyvenv_cfg(maybe_venv_bin_dir)
         if not pyvenv_cfg:
@@ -1032,7 +1032,7 @@ def _create_isolated_cmd(
     #
     # See:
     # + https://github.com/python/mypy/issues/4211
-    # + https://www.python.org/dev/peps/pep-0484/#the-typing-module
+    # + https://peps.python.org/pep-0484/#the-typing-module
     _PYENV = ()  # type: Union[Tuple[()],Optional[Pyenv]]
 
     @classmethod

pex/interpreter_constraints.py

@@ -333,7 +333,7 @@ class Value(Enum.Value):
 # This value is based off of:
 # 1. Past releases: https://www.python.org/downloads/ where the max patch level was achieved by
 #    2.7.18.
-# 2. The 3.9+ annual release cycle formalization: https://www.python.org/dev/peps/pep-0602/ where
+# 2. The 3.9+ annual release cycle formalization: https://peps.python.org/pep-0602/ where
 #    the last bugfix release will be at a patch level of ~10 and then 3.5 years of security fixes
 #    as needed before going to EOL at the 5-year mark.
 DEFAULT_MAX_PATCH = 30

pex/pep_376.py

@@ -112,7 +112,7 @@ def find_and_replace_path_components(
 class InstalledFile(object):
     """The record of a single installed file from a PEP 376 RECORD file.
 
-    See: https://www.python.org/dev/peps/pep-0376/#record
+    See: https://peps.python.org/pep-0376/#record
     """
 
     _PYTHON_VER_PLACEHOLDER = "pythonX.Y"
@@ -469,7 +469,7 @@ class DistInfoFile(object):
 class Record(object):
     """Represents the PEP-376 RECORD of an installed wheel.
 
-    See: https://www.python.org/dev/peps/pep-0376/#record
+    See: https://peps.python.org/pep-0376/#record
     """
 
     @classmethod
@@ -481,7 +481,7 @@ def write(
         # type: (...) -> None
 
         # The RECORD is a csv file with the path to each installed file in the 1st column.
-        # See: https://www.python.org/dev/peps/pep-0376/#record
+        # See: https://peps.python.org/pep-0376/#record
         with safe_open(dst, "w") as fp:
             csv_writer = cast(
                 "CSVWriter",
@@ -499,7 +499,7 @@ def read(
         # type: (...) -> Iterator[InstalledFile]
 
         # The RECORD is a csv file with the path to each installed file in the 1st column.
-        # See: https://www.python.org/dev/peps/pep-0376/#record
+        # See: https://peps.python.org/pep-0376/#record
         for line, (path, fingerprint, file_size) in enumerate(
             csv.reader(lines, delimiter=",", quotechar='"'), start=1
         ):

pex/pep_425.py

@@ -51,7 +51,7 @@ class CompatibilityTags(object):
     Tags are ordered most specific 1st to most generic last. The more specific a tag, the lower its
     rank value, with the most specific tag (best match) being ranked 0.
 
-    See: https://www.python.org/dev/peps/pep-0425/#use
+    See: https://peps.python.org/pep-0425/#use
     """
 
     @classmethod
@@ -65,7 +65,7 @@ def from_wheel(cls, wheel):
                 )
             )
         wheel_stem, _ = os.path.splitext(os.path.basename(wheel))
-        # Wheel filename format: https://www.python.org/dev/peps/pep-0427/#file-name-convention
+        # Wheel filename format: https://peps.python.org/pep-0427/#file-name-convention
         # `{distribution}-{version}(-{build tag})?-{python tag}-{abi tag}-{platform tag}.whl`
         wheel_components = wheel_stem.rsplit("-", 3)
         if len(wheel_components) != 4:

pex/pep_440.py

@@ -34,7 +34,7 @@ def _ensure_ascii_str(text):
 @functools.total_ordering
 @attr.s(frozen=True, order=False)
 class Version(object):
-    """A PEP-440 normalized version: https://www.python.org/dev/peps/pep-0440/#normalization"""
+    """A PEP-440 normalized version: https://peps.python.org/pep-0440/#normalization"""
 
     raw = attr.ib(eq=False, converter=_ensure_ascii_str)  # type: str
     normalized = attr.ib(init=False)  # type: str
@@ -45,7 +45,7 @@ class Version(object):
     def __attrs_post_init__(self):
         # type: () -> None
 
-        # Although https://www.python.org/dev/peps/pep-0440 which does not allow a `-` in modern
+        # Although https://peps.python.org/pep-0440 which does not allow a `-` in modern
         # versions, it also stipulates that all versions (legacy) must be handled. It turns out
         # wheel normalizes `-` to `_` and Pip has had to deal with this:
         #   https://github.com/pypa/pip/issues/1150

pex/pep_503.py

@@ -28,7 +28,7 @@ def _ensure_ascii_str(text):
 class ProjectName(object):
     """Encodes a canonicalized project name as per PEP-503.
 
-    See: https://www.python.org/dev/peps/pep-0503/#normalized-names
+    See: https://peps.python.org/pep-0503/#normalized-names
     """
 
     class InvalidError(ValueError):

pex/pep_508.py

@@ -37,7 +37,7 @@ def _convert_non_pep_440_dev_versions(python_full_version):
 class MarkerEnvironment(object):
     """A PEP-508 marker environment.
 
-    See: https://www.python.org/dev/peps/pep-0508/#environment-markers
+    See: https://peps.python.org/pep-0508/#environment-markers
     """
 
     @classmethod
@@ -89,13 +89,13 @@ def from_platform(cls, platform):
                 # + linux_x86_64
                 # + manylinux{1,2010,2014}_x86_64
                 # For the manylinux* See:
-                # + manylinux1: https://www.python.org/dev/peps/pep-0513/
-                # + manylinux2010: https://www.python.org/dev/peps/pep-0571/
-                # + manylinux2014: https://www.python.org/dev/peps/pep-0599/
+                # + manylinux1: https://peps.python.org/pep-0513/
+                # + manylinux2010: https://peps.python.org/pep-0571/
+                # + manylinux2014: https://peps.python.org/pep-0599/
                 platform_machine = platform.platform.split("_", 1)[-1]
             else:
                 # E.G.: manylinux_<glibc major>_<glibc_minor>_x86_64
-                # See: https://www.python.org/dev/peps/pep-0600/
+                # See: https://peps.python.org/pep-0600/
                 platform_machine = platform.platform.split("_", 3)[-1]
             platform_system = "Linux"
             sys_platform = "linux2" if major_version == 2 else "linux"

pex/pip/foreign_platform/__init__.py

@@ -37,7 +37,7 @@ def iter_platform_args(
     # the machines it controls. This is in contrast to the public PyPI index which does not
     # allow non-manylinux-compliant wheels to be uploaded at all since the wheels it serves can
     # be used on unknown target linux machines (for background on this, see:
-    # https://www.python.org/dev/peps/pep-0513/#rationale). If that organization wishes to
+    # https://peps.python.org/pep-0513/#rationale). If that organization wishes to
     # consume both its own custom-built wheels as well as other manylinux-compliant wheels in
     # the same application, it needs to advertise that the target machine supports both
     # `linux_x86_64` wheels and `manylinux2014_x86_64` wheels (for example).