From c64503e280c3e503c102bf5c4724851e081c8dec Mon Sep 17 00:00:00 2001
From: Sumana Harihareswara <sh@changeset.nyc>
Date: Fri, 23 Feb 2018 17:48:57 -0500
Subject: [PATCH 1/2] Improve docs headers and tables of contents

---
 docs/api-reference/index.rst         | 5 ++++-
 docs/api-reference/json.rst          | 4 ++++
 docs/application.rst                 | 4 ++--
 docs/development/getting-started.rst | 2 +-
 4 files changed, 11 insertions(+), 4 deletions(-)

diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst
index 491b370874b9..0000ed4a3ac7 100644
--- a/docs/api-reference/index.rst
+++ b/docs/api-reference/index.rst
@@ -1,8 +1,11 @@
 API Reference
 =============
 
+Warehouse has several API endpoints. See :doc:`../application` for the
+parts of Warehouse that generate them.
+
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     feeds
     json
diff --git a/docs/api-reference/json.rst b/docs/api-reference/json.rst
index 5bed0dc64f70..1aad53dfb4e6 100644
--- a/docs/api-reference/json.rst
+++ b/docs/api-reference/json.rst
@@ -3,6 +3,8 @@ JSON API
 
 PyPI offers two JSON endpoints.
 
+Project
+-------
 
 .. http:get:: /pypi/<project_name>/json
 
@@ -117,6 +119,8 @@ PyPI offers two JSON endpoints.
 
     :statuscode 200: no error
 
+Release
+-------
 
 .. http:get:: /pypi/<project_name>/<version>/json
 
diff --git a/docs/application.rst b/docs/application.rst
index d68f3fd61832..45fe01c526aa 100644
--- a/docs/application.rst
+++ b/docs/application.rst
@@ -1,5 +1,5 @@
-The Warehouse codebase
-======================
+Warehouse codebase
+==================
 
 Warehouse uses the
 `Pyramid`_ web framework, the
diff --git a/docs/development/getting-started.rst b/docs/development/getting-started.rst
index a9849364d754..facb45f78153 100644
--- a/docs/development/getting-started.rst
+++ b/docs/development/getting-started.rst
@@ -264,7 +264,7 @@ https://github.com/chadoe/docker-cleanup-volumes)
 
 
 ``make initdb`` is slow or appears to make no progress
-------------------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This typically occur when Docker is not allocated enough memory to perform the
 migrations. Try modifying your Docker configuration to allow more RAM for each

From a69a2fc3a63216a6606ebcd38b262f25e22e0707 Mon Sep 17 00:00:00 2001
From: Sumana Harihareswara <sh@changeset.nyc>
Date: Fri, 23 Feb 2018 17:49:36 -0500
Subject: [PATCH 2/2] Document legacy upload API endpoint

---
 docs/api-reference/legacy.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/docs/api-reference/legacy.rst b/docs/api-reference/legacy.rst
index bfb16c04c5d1..e86056448a24 100644
--- a/docs/api-reference/legacy.rst
+++ b/docs/api-reference/legacy.rst
@@ -122,3 +122,14 @@ The Simple API implements the HTML-based package index API as specified in `PEP
 
 .. _`pypi-legacy`: https://pypi.python.org/
 .. _`PEP 503`: https://www.python.org/dev/peps/pep-0503/
+
+Upload API
+----------
+
+The API endpoint served at `upload.pypi.org/legacy/
+<https://upload.pypi.org/legacy/>`_ is Warehouse's emulation of the
+legacy PyPI upload API. This is the endpoint that tools such as `twine
+<http://twine.readthedocs.io/>`_ and `distutils
+<https://docs.python.org/3.6/distutils/packageindex.html#the-upload-command>`_
+use to `upload distributions to PyPI
+<https://packaging.python.org/tutorials/distributing-packages/>`_.