diff --git a/docs/dev/api-reference/bigquery-datasets.rst b/docs/dev/api-reference/bigquery-datasets.rst deleted file mode 100644 index 431da8625890..000000000000 --- a/docs/dev/api-reference/bigquery-datasets.rst +++ /dev/null @@ -1,10 +0,0 @@ -BigQuery Datasets -================= - -.. important:: - - This API documentation has been migrated to a new page in - the `user documentation `_: - - * `BigQuery Datasets `_ - diff --git a/docs/dev/api-reference/feeds.rst b/docs/dev/api-reference/feeds.rst deleted file mode 100644 index cd9e398d6d0a..000000000000 --- a/docs/dev/api-reference/feeds.rst +++ /dev/null @@ -1,9 +0,0 @@ -Feeds -===== - -.. important:: - - This API documentation has been migrated to a new page in - the `user documentation `_: - - * `RSS Feeds `_ diff --git a/docs/dev/api-reference/index.rst b/docs/dev/api-reference/index.rst index 46a7bb4a3833..f34bd3a956f1 100644 --- 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 `_. - Please see `issue #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 - `_. - -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 deleted file mode 100644 index 6de57cc436dd..000000000000 --- a/docs/dev/api-reference/integration-guide.rst +++ /dev/null @@ -1,10 +0,0 @@ -Integration guide -================= - -.. important:: - - This API documentation has been migrated to a new page in - the `user documentation `_: - - * `API - Integration Guide `_ - diff --git a/docs/dev/api-reference/json.rst b/docs/dev/api-reference/json.rst deleted file mode 100644 index 5e0a9b910685..000000000000 --- a/docs/dev/api-reference/json.rst +++ /dev/null @@ -1,9 +0,0 @@ -JSON API -======== - -.. important:: - - This API documentation has been migrated to a new page in - the `user documentation `_: - - * `JSON API `_ diff --git a/docs/dev/api-reference/legacy.rst b/docs/dev/api-reference/legacy.rst deleted file mode 100644 index 90bdad6ba097..000000000000 --- a/docs/dev/api-reference/legacy.rst +++ /dev/null @@ -1,10 +0,0 @@ -Legacy API -========== - -.. important:: - - This API documentation has been migrated to two new pages in - the `user documentation `_: - - * `Index API `_ - * `Upload API `_ diff --git a/docs/dev/api-reference/stats.rst b/docs/dev/api-reference/stats.rst deleted file mode 100644 index e0e8bc602008..000000000000 --- a/docs/dev/api-reference/stats.rst +++ /dev/null @@ -1,9 +0,0 @@ -Stats API -========= - -.. important:: - - This API documentation has been migrated to a new page in - the `user documentation `_: - - * `Stats API `_ diff --git a/docs/dev/api-reference/xml-rpc.rst b/docs/dev/api-reference/xml-rpc.rst index 095900c1e3f4..327a998459cd 100644 --- 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 `_. - ``release_downloads`` and ``top_packages`` No longer supported. Use - :doc:`Google BigQuery ` instead (`guidance + `BigQuery Datasets `_ instead (`guidance `_, `tips `_). @@ -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 `_ should be used. ``package_urls(package_name, version)`` +++++++++++++++++++++++++++++++++++++++ -Deprecated, :doc:`json` should be used. +Deprecated, the `JSON API `_ should be used. ``top_packages(num=None)`` ++++++++++++++++++++++++++ -Use :doc:`Google BigQuery ` +Use `BigQuery Datasets `_ instead (`guidance `_, `tips `_). @@ -187,25 +187,28 @@ driven by unidentified traffic, presumably automated. `See historical incident ``list_packages()`` +++++++++++++++++++ -Use the :doc:`Simple API ` +Use the `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 ` to query for available releases -of a given project. +Use the `JSON API `_ or +`Index API `_ to query for available +releases of a given project. ``release_urls(package_name, release_version)`` +++++++++++++++++++++++++++++++++++++++++++++++ -Use :doc:`json` or :doc:`Simple API ` to query for file download URLs -for a given release. +Use the `JSON API `_ or +`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 ` to query for metadata of a given -release. +Use the `JSON API `_ or +`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 index e265b3924036..363d5c09397c 100644 --- 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 index 325bc6c5d181..db71d009fa7a 100644 --- 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 `_ /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 index 8e346dac4cb6..859ed30626ea 100644 --- 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 index 905829728b99..b78969d5e8e5 100644 --- 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