docs: redirect all old API docs to new equivalents (#17213)

* docs: redirect all old API docs to new equivalents Signed-off-by: William Woodruff <[email protected]> * restore index, fix links Signed-off-by: William Woodruff <[email protected]> * Update docs/dev/api-reference/index.rst Co-authored-by: Dustin Ingram <[email protected]> * Update docs/dev/conf.py Co-authored-by: Dustin Ingram <[email protected]> * Update docs/dev/conf.py --------- Signed-off-by: William Woodruff <[email protected]> Co-authored-by: Dustin Ingram <[email protected]>
pypi · Dec 3, 2024 · c9231a6 · c9231a6
1 parent 9f9413d
commit c9231a6
Show file tree

Hide file tree

Showing 12 changed files with 37 additions and 141 deletions.
diff --git a/docs/dev/api-reference/bigquery-datasets.rst b/docs/dev/api-reference/bigquery-datasets.rst
diff --git a/docs/dev/api-reference/feeds.rst b/docs/dev/api-reference/feeds.rst
diff --git a/docs/dev/api-reference/index.rst b/docs/dev/api-reference/index.rst
@@ -3,75 +3,10 @@ API reference
 
 .. note::
 
-  API documentation is being moved to PyPI's
+  All API documentation except for :doc:`xml-rpc` has been moved to the
   `user documentation site <https://docs.pypi.org/api/>`_.
 
-  Please see `issue #16541 <https://github.com/pypi/warehouse/issues/16541>`_
-  for more information and status updates.
-
-Warehouse has several API endpoints. See :doc:`../application` for the
-parts of Warehouse that generate them.
-
-API policies
-------------
-
-Please be aware of these PyPI API policies:
-
-Caching
-~~~~~~~
-
-All API requests are cached. Requests to the JSON, RSS or Legacy APIs are
-cached by our CDN provider. You can determine if you've hit the cache based on
-the ``X-Cache`` and ``X-Cache-Hits`` headers in the response.
-
-Requests to the JSON, RSS and Legacy APIs also provide an ``ETag`` header. If
-you're making a lot of repeated requests, ensure your API consumer will respect
-this header to determine whether to actually repeat a request or not.
-
-The XML-RPC API does not have the ability to indicate cached responses.
-
-Rate limiting
-~~~~~~~~~~~~~
-
-Due to the heavy caching and CDN use, there is currently no rate limiting of
-PyPI APIs at the edge. The XML-RPC API may be rate limited if usage is causing
-degradation of service.
-
-In addition, PyPI reserves the right to temporarily or permanently prohibit a
-consumer based on irresponsible activity.
-
-If you plan to make a lot of requests to a PyPI API, adhere to these
-suggestions:
-
-* Set your consumer's ``User-Agent`` header to uniquely identify your requests.
-  Adding your contact information to this value would be helpful as well.
-* Try not to make a lot of requests (thousands) in a short amount of time
-  (minutes). Generally PyPI can handle it, but it's preferred to make requests
-  in serial over a longer amount of time if possible.
-* If your consumer is actually an organization or service that will be
-  downloading a lot of packages from PyPI, consider `using your own index
-  mirror or cache
-  <https://packaging.python.org/guides/index-mirrors-and-caches/>`_.
-
-API Preference
-~~~~~~~~~~~~~~
-
-For periodically checking for new packages or updates to existing packages,
-use our RSS feeds.
-
-No new integrations should use the XML-RPC APIs as they are planned for
-deprecation. Existing consumers should migrate to JSON/RSS/Legacy APIs.
-
-Available APIs & Datasets
--------------------------
-
 .. toctree::
     :maxdepth: 2
 
-    feeds
-    json
-    legacy
-    stats
     xml-rpc
-    integration-guide
-    bigquery-datasets
diff --git a/docs/dev/api-reference/integration-guide.rst b/docs/dev/api-reference/integration-guide.rst
diff --git a/docs/dev/api-reference/json.rst b/docs/dev/api-reference/json.rst
diff --git a/docs/dev/api-reference/legacy.rst b/docs/dev/api-reference/legacy.rst
diff --git a/docs/dev/api-reference/stats.rst b/docs/dev/api-reference/stats.rst
diff --git a/docs/dev/api-reference/xml-rpc.rst b/docs/dev/api-reference/xml-rpc.rst
@@ -85,7 +85,7 @@ Changes to XMLRPC API
   incident <https://status.python.org/incidents/grk0k7sz6zkp>`_.
 
 - ``release_downloads`` and ``top_packages`` No longer supported. Use
-  :doc:`Google BigQuery <bigquery-datasets>` instead (`guidance
+  `BigQuery Datasets <https://docs.pypi.org/api/bigquery/>`_ instead (`guidance
   <https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
   `tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).
 
@@ -163,17 +163,17 @@ Deprecated in favor of ``changelog_since_serial``.
 ``package_data(package_name, version)``
 +++++++++++++++++++++++++++++++++++++++
 
-Deprecated, :doc:`json` should be used.
+Deprecated, the `JSON API <https://docs.pypi.org/api/json/>`_ should be used.
 
 ``package_urls(package_name, version)``
 +++++++++++++++++++++++++++++++++++++++
 
-Deprecated, :doc:`json` should be used.
+Deprecated, the `JSON API <https://docs.pypi.org/api/json/>`_ should be used.
 
 ``top_packages(num=None)``
 ++++++++++++++++++++++++++
 
-Use :doc:`Google BigQuery <bigquery-datasets>`
+Use `BigQuery Datasets <https://docs.pypi.org/api/bigquery/>`_
 instead (`guidance <https://packaging.python.org/guides/analyzing-pypi-package-downloads/>`_,
 `tips <https://langui.sh/2016/12/09/data-driven-decisions/>`_).
 
@@ -187,25 +187,28 @@ driven by unidentified traffic, presumably automated. `See historical incident
 ``list_packages()``
 +++++++++++++++++++
 
-Use the :doc:`Simple API <legacy>`
+Use the `Index API <https://docs.pypi.org/api/index-api/>`_
 to query for list of project names with releases on PyPI.
 
 ``package_releases(package_name, show_hidden=False)``
 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Use :doc:`json` or :doc:`Simple API <legacy>` to query for available releases
-of a given project.
+Use the `JSON API <https://docs.pypi.org/api/json/>`_ or
+`Index API <https://docs.pypi.org/api/index-api/>`_ to query for available
+releases of a given project.
 
 ``release_urls(package_name, release_version)``
 +++++++++++++++++++++++++++++++++++++++++++++++
 
-Use :doc:`json` or :doc:`Simple API <legacy>` to query for file download URLs
-for a given release.
+Use the `JSON API <https://docs.pypi.org/api/json/>`_ or
+`Index API <https://docs.pypi.org/api/index-api/>`_ to query for file download
+URLs for a given release.
 
 ``release_data(package_name, release_version)``
 +++++++++++++++++++++++++++++++++++++++++++++++
 
-Use :doc:`json` or :doc:`Simple API <legacy>` to query for metadata of a given
-release.
+Use the `JSON API <https://docs.pypi.org/api/json/>`_ or
+`Index API <https://docs.pypi.org/api/index-api/>`_ to query for metadata of a
+given release.
 
 .. _pypi-announce: https://mail.python.org/mailman3/lists/pypi-announce.python.org/
diff --git a/docs/dev/conf.py b/docs/dev/conf.py
@@ -14,7 +14,6 @@
 import os
 from datetime import datetime
 
-
 base_dir = os.path.join(os.path.abspath(os.path.dirname(__file__)), "..")
 
 # -- General configuration ------------------------------------------------
@@ -29,15 +28,25 @@
     "myst_parser",
     "sphinxcontrib.mermaid",
     "sphinx_copybutton",
+    "sphinx_reredirects",
 ]
 
+redirects = {
+    "api-reference/feeds": "https://docs.pypi.org/api/feeds/",
+    "api-reference/json": "https://docs.pypi.org/api/json/",
+    "api-reference/legacy": "https://docs.pypi.org/api/index-api/",
+    "api-reference/stats": "https://docs.pypi.org/api/stats/",
+    "api-reference/integration-guide": "https://docs.pypi.org/api/#integration-guide",
+    "api-reference/bigquery-datasets": "https://docs.pypi.org/api/bigquery",
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
 # The suffix of source filenames.
 source_suffix = {
-    ".rst": 'restructuredtext',
-    ".md": 'markdown',
+    ".rst": "restructuredtext",
+    ".md": "markdown",
 }
 
 # The master toctree document.
@@ -56,9 +65,9 @@
 
 # Patterns to during `make linkcheck`
 linkcheck_ignore = [
-    r'http://localhost.*',
-    'http://134.122.111.11',  # example IP
-    'https://web.libera.chat/#pypa,#pypa-dev',  # can't visit anchors
+    r"http://localhost.*",
+    "http://134.122.111.11",  # example IP
+    "https://web.libera.chat/#pypa,#pypa-dev",  # can't visit anchors
 ]
 
 

diff --git a/docs/dev/development/legacy-application-structure.rst b/docs/dev/development/legacy-application-structure.rst
@@ -16,7 +16,7 @@ URL           Purpose
 /security     Page giving contact and other information regarding site security
 /id           OpenID endpoint
 /oauth        OAuth endpoint
-/simple       Simple API as given in :doc:`../api-reference/legacy`
+/simple       Simple API as given in `Index API <https://docs.pypi.org/api/index-api/>`_
 /packages     Serve up a package file
 /mirrors      Page listing legacy mirrors (not to be retained)
 /serversig    Legacy mirroring support (no-one uses it: not to be retained)

diff --git a/requirements/docs-dev.in b/requirements/docs-dev.in
@@ -4,4 +4,5 @@ sphinx-autobuild
 sphinx-copybutton
 sphinxcontrib-httpdomain
 sphinxcontrib-mermaid
+sphinx-reredirects
 myst-parser
diff --git a/requirements/docs-dev.txt b/requirements/docs-dev.txt
@@ -349,6 +349,7 @@ sphinx==8.1.3 \
     #   sphinx-autobuild
     #   sphinx-basic-ng
     #   sphinx-copybutton
+    #   sphinx-reredirects
     #   sphinxcontrib-httpdomain
     #   sphinxcontrib-mermaid
 sphinx-autobuild==2024.10.3 \
@@ -363,6 +364,10 @@ sphinx-copybutton==0.5.2 \
     --hash=sha256:4cf17c82fb9646d1bc9ca92ac280813a3b605d8c421225fd9913154103ee1fbd \
     --hash=sha256:fb543fd386d917746c9a2c50360c7905b605726b9355cd26e9974857afeae06e
     # via -r requirements/docs-dev.in
+sphinx-reredirects==0.1.5 \
+    --hash=sha256:444ae1438fba4418242ca76d6a6de3eaee82aaf0d8f2b0cac71a15d32ce6eba2 \
+    --hash=sha256:cfa753b441020a22708ce8eb17d4fd553a28fc87a609330092917ada2a6da0d8
+    # via -r requirements/docs-dev.in
 sphinxcontrib-applehelp==2.0.0 \
     --hash=sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1 \
     --hash=sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5