chore(deps): replace sphinx with mkdocs

bin/dev-docs

@@ -1,5 +1,4 @@
 #!/bin/bash
 set -ex
 
-make -C docs/dev/ doctest SPHINXOPTS="-W"
-make -C docs/dev/ html SPHINXOPTS="-W"
+mkdocs build -f docs/mkdocs-dev-docs.yml --strict

bin/rtd-docs

@@ -5,14 +5,14 @@ set -e
 set -x
 
 if [ "${READTHEDOCS_PROJECT}" = "warehouse" ]; then
-  if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/dev requirements/docs-dev.txt .readthedocs.yaml; then
+  if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/dev requirements/docs-dev.txt .readthedocs.yaml docs/mkdocs-dev-docs.yml; then
     echo "Nothing relevant changed, skipping build..."
     exit 183;
   fi
   pip install -r requirements/docs-dev.txt
   asdf reshim
-  make -C docs/dev/ html
-  mkdir _readthedocs && mv docs/dev/_build/html _readthedocs/html
+  mkdocs build -f docs/mkdocs-dev-docs.yml
+  mkdir _readthedocs && mv docs/dev-site _readthedocs/html
 fi
 
 if [ "${READTHEDOCS_PROJECT}" = "docspypiorg" ]; then

docker-compose.yml

@@ -256,9 +256,11 @@ services:
       context: .
       target: docs
     image: warehouse:docker-compose-docs
-    command: sphinx-autobuild --host 0.0.0.0 "docs/dev/" "docs/dev/_build"
+    command: mkdocs serve -a 0.0.0.0:8000 -f docs/mkdocs-dev-docs.yml
+    stop_signal: SIGINT
     volumes:
       - ./bin:/opt/warehouse/src/bin:z
+      - ./docs/mkdocs-dev-docs.yml:/opt/warehouse/src/docs/mkdocs-dev-docs.yml:z
       - ./docs:/opt/warehouse/src/docs:z
     ports:
       - "10002:8000"

docs/.gitignore

@@ -1,2 +1,3 @@
 user-site
 blog-site
+dev-site

docs/dev/api-reference/index.md

@@ -0,0 +1,5 @@
+# API reference
+
+!!! note
+    All API documentation except for [XML-RPC](xml-rpc.md) has been moved to the
+    [user documentation site](https://docs.pypi.org/api/).