docs: move stats API to user docs (#17161)

Signed-off-by: William Woodruff <william@trailofbits.com>
Co-authored-by: Dustin Ingram <di@users.noreply.github.com>

docs/dev/api-reference/stats.rst

@@ -1,48 +1,9 @@
 Stats API
 =========
 
-PyPI offers a JSON stats endpoint via a ``Accept: application/json`` GET
-request. Without the ``Accept`` header set, you will be returned a HTML page.
+.. important::
 
-**Example Client**: https://github.com/cooperlees/pypistats
+  This API documentation has been migrated to a new page in
+  the `user documentation <https://docs.pypi.org/>`_:
 
-Project
--------
-
-.. http:get:: /stats/
-
-    Returns statistics in JSON format. This includes:
-    - Total size of PyPI packages in bytes
-    - Top 100 packages + their size in bytes
-
-    **Example Request**:
-
-    - `curl -H "Accept: application/json" https://pypi.org/stats/`
-
-    .. code:: http
-
-        GET /stats HTTP/1.1
-        Host: pypi.org
-        Accept: application/json
-
-    **Example response**:
-
-    .. code:: json
-
-      {
-        "top_packages": {
-          "CodeIntel": {
-            "size": 23767329521
-          },
-          "Fiona": {
-            "size": 6209535709
-          },
-          "FlexGet": {
-            "size": 4387002448
-          },
-          "...": "..."
-        },
-        "total_packages_size": 23965450269
-      }
-
-    :statuscode 200: no error
+  * `Stats API <https://docs.pypi.org/api/stats/>`_

docs/mkdocs-user-docs.yml

@@ -22,6 +22,12 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
+  - pymdownx.magiclink:
+      repo_url_shorthand: true
+      normalize_issue_symbols: true
+      provider: github
+      user: pypi
+      repo: warehouse
 theme:
   name: material
   logo: assets/logo.png
@@ -84,3 +90,4 @@ nav:
       - "api/index-api.md"
       - "api/upload.md"
       - "api/integrity.md"
+      - "api/stats.md"

docs/user/api/stats.md

@@ -0,0 +1,53 @@
+# Stats API
+
+!!! important
+
+    You **must** set `Accept: application/json` in your requests to this API.
+    Without the `Accept` header, you will be returned an HTML page.
+
+!!! tip
+
+    An example stats API client can be found at @coopherlees/pypistats.
+
+## Routes
+
+### Project stats
+
+Route: `GET /stats/`
+
+Returns statistics in JSON format. This includes:
+
+- Total size of PyPI packages in bytes
+- Top 100 packages + their size in bytes
+
+Status codes:
+
+* `200 OK` - no error
+
+Example request:
+
+```http
+GET /stats HTTP/1.1
+Host: pypi.org
+Accept: application/json
+```
+
+??? note "Example JSON response"
+
+    ```json
+    {
+      "top_packages": {
+        "CodeIntel": {
+          "size": 23767329521
+        },
+        "Fiona": {
+          "size": 6209535709
+        },
+        "FlexGet": {
+          "size": 4387002448
+        },
+        "...": "..."
+      },
+      "total_packages_size": 23965450269
+    }
+    ```