Slightly clarify the relationship to warehouse. (#308)

* Slightly clarify the relationship to warehouse.

Closes: #307

* Wording tweaks and split out the related software into its own section.

* Separate the note in a note directive

Co-authored-by: Matthew Planchard <mplanchard@users.noreply.github.com>

Co-authored-by: Matthew Planchard <mplanchard@users.noreply.github.com>

README.rst

@@ -24,6 +24,17 @@ Wheels, bdists, eggs and accompanying PGP-signatures can be uploaded
 either with ``pip``, ``setuptools``, ``twine``, ``pypi-uploader``, or simply copied
 with ``scp``.
 
+.. note::
+   The official software powering PyPI_ is Warehouse_. However, Warehouse_
+   is fairly specialized to be ``pypi.org``'s own software, and should not
+   be used in other contexts. In particular, it does not officially support
+   being used as a custom package index by users wishing to serve their own
+   packages.
+
+   ``pypiserver`` implements the same interfaces as `PyPI`_, allowing
+   standard Python packaging tooling such as ``pip`` and ``twine`` to
+   interact with it as a package index just as they would with PyPI_, while
+   making it much easier to get a running index server.
 
 .. contents:: Table of Contents
   :backlinks: top
@@ -906,15 +917,27 @@ among the most popular alternatives:
 - `flask-pypi-proxy <http://flask-pypi-proxy.readthedocs.org/>`_
   A proxy for PyPI that also enables also uploading custom packages.
 
-- `twine`_:
+- Check this SO question: `How to roll my own pypi
-  A command-line utility for interacting with PyPI or ``pypiserver``.
+  <http://stackoverflow.com/questions/1235331/how-to-roll-my-own-pypi>`_
+
+
+Related Software
+================
+
+Though not direct alternatives for ``pypiserver``'s use as an index
+server, the following is a list of related software projects that you
+may want to familiarize with:
 
 - `pypi-uploader`_:
   A command-line utility to upload packages to your ``pypiserver`` from pypi without
   having to store them locally first.
 
-- Check this SO question: `How to roll my own pypi
+- `twine`_:
-  <http://stackoverflow.com/questions/1235331/how-to-roll-my-own-pypi>`_
+  A command-line utility for interacting with PyPI or ``pypiserver``.
+
+- `warehouse`_:
+  the software that powers PyPI_ itself. It is not generally intended to
+  be run by end-users.
 
 
 Licensing
@@ -926,7 +949,9 @@ See the ``LICENSE.txt`` file.
 
 
 .. _bottle: http://bottlepy.org
+.. _PyPA: https://www.pypa.io/en/latest/
 .. _PyPI: https://pypi.org
+.. _Warehouse: https://github.com/pypa/warehouse/
 .. _twine: https://pypi.org/project/twine/
 .. _pypi-uploader: https://pypi.org/project/pypi-uploader/
 .. _python-pam: https://pypi.org/project/python-pam/