Merge branch 'master' into setup-py-updatesetup-py-update

10 files changed, 239 insertions, 77 deletions

diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 0000000..91f36ae
--- /dev/null
+++ b/docs/Makefile
@@ -0,0 +1,107 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    = -W
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html text web pickle htmlhelp latex latexpdf xelatexpdf changes linkcheck epub doctest
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  text       to make text files"
+	@echo "  pickle     to make pickle files (usable by e.g. sphinx-web)"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  xelatexpdf to make LaTeX files and run them through xelatex"
+	@echo "  changes    to make an overview over all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  epub       to make an epub"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+xelatexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through xelatex..."
+	$(MAKE) PDFLATEX=xelatex -C $(BUILDDIR)/latex all-pdf
+	@echo "xelatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+html:
+	mkdir -p $(BUILDDIR)/html $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+text:
+	mkdir -p $(BUILDDIR)/text $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/text."
+
+pickle:
+	mkdir -p $(BUILDDIR)/pickle $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files or run"
+	@echo "  sphinx-web $(BUILDDIR)/pickle"
+	@echo "to start the sphinx-web server."
+
+web: pickle
+
+htmlhelp:
+	mkdir -p $(BUILDDIR)/htmlhelp $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+latex:
+	mkdir -p $(BUILDDIR)/latex $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	cp _static/*.png $(BUILDDIR)/latex
+	./convert_images.sh
+	cp _static/latex-warning.png $(BUILDDIR)/latex
+	cp _static/latex-note.png $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make xelatexpdf' to build a PDF file from them."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF file is in $(BUILDDIR)/latex."
+
+changes:
+	mkdir -p $(BUILDDIR)/changes $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	mkdir -p $(BUILDDIR)/linkcheck $(BUILDDIR)/doctrees
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
diff --git a/docs/conf.py b/docs/conf.py
index 17bdf1c..00d8761 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -11,7 +11,8 @@
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
-import sys
+import datetime
+import pkg_resources
 import pylons_sphinx_themes
 
 # If your extensions are in another directory, add it here.
@@ -22,28 +23,38 @@ import pylons_sphinx_themes
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+]
+
+# Looks for objects in external projects
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+# templates_path = ['_templates']
 
 # The suffix of source filenames.
-source_suffix = '.txt'
+source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
+thisyear = datetime.datetime.now().year
 project = 'Paste Deploy'
-copyright = '2011, Ian Bicking and contributors'
+copyright = '2011-%s, Ian Bicking and contributors' % thisyear
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The short X.Y version.
-version = '1.5'
+version = pkg_resources.get_distribution('pastedeploy').version
+
 # The full version, including alpha/beta/rc tags.
-release = '1.5.2'
+release = version
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -86,7 +97,7 @@ html_theme_options = dict(
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
diff --git a/docs/index.txt b/docs/index.rst
index e6c4351..929b78b 100644
--- a/docs/index.txt
+++ b/docs/index.rst
@@ -35,13 +35,12 @@ without knowing any Python, or the details of the WSGI application or
 its container.
 
 Paste Deployment currently does not require other parts of `Paste
-<http://pythonpaste.org>`_, and is distributed as a separate package.
+<https://pythonpaste.readthedocs.io/en/latest/>`_, and is distributed as a separate package.
 
-To see updates that have been made to Paste Deploy see the `news file
-<news.html>`_.
+To see updates that have been made to Paste Deploy see the :doc:`news file <news>`.
 
 Paste Deploy is released under the `MIT license
-<http://www.opensource.org/licenses/mit-license.php>`_.
+<https://opensource.org/licenses/mit-license.php>`_.
 
 Status
 ------
@@ -69,26 +68,27 @@ modern replacement
 `distribute <https://pypi.org/project/distribute/>`_ installed.
 For Python 3.x you need distribute as setuptools does not work on it.
 
-Then you can install Paste Deployment using `pip
-<http://www.pip-installer.org/en/latest/installing.html>`_ by running::
+Then you can install Paste Deployment using `pip <https://pypi.org/project/pip/>`_ by running:
 
-    $ sudo pip install PasteDeploy
+.. code-block:: bash
 
-If you want to track development, do::
+    pip install PasteDeploy
 
-    $ hg clone http://bitbucket.org/ianb/pastedeploy
-    $ cd pastedeploy
-    $ sudo python setup.py develop
+If you want to track development, do:
 
-This will install the package globally, but will load the files in the
+.. code-block:: bash
+
+    git clone https://github.com/Pylons/pastedeploy
+    cd pastedeploy
+    pip install -e .
+
+This will install the package locally, and will load the files in the
 checkout.  You can also simply install ``PasteDeploy==dev``.
 
-For downloads and other information see the `Cheese Shop PasteDeploy
-page <http://cheeseshop.python.org/pypi/PasteDeploy>`_.
+For downloads and other information see the `PyPI PasteDeploy page <https://pypi.org/project/PasteDeploy/>`_.
 
-A complimentary package is `Paste Script </script/>`_.  To install
-that, use ``pip install PasteScript`` (or ``pip install
-PasteScript==dev``).
+A complementary package is `Paste Script <https://pypi.org/project/PasteScript/>`_.
+To install that, use ``pip install PasteScript`` (or ``pip install PasteScript==dev``).
 
 From the User Perspective
 -------------------------
@@ -101,7 +101,7 @@ The primary interaction with Paste Deploy is through its configuration
 files.  The primary thing you want to do with a configuration file is
 serve it.  To learn about serving configuration files, see `the
 ``paster serve`` command
-<http://pythonpaste.org/script/#paster-serve>`_.
+<https://pastescript.readthedocs.io/en/latest/#paster-serve>`_.
 
 The Config File
 ~~~~~~~~~~~~~~~
@@ -112,7 +112,7 @@ the part after the ``:`` is the "name" of the section, and the part
 before gives the "type".  Other sections are ignored.  
 
 The format is a simple `INI format
-<http://en.wikipedia.org/wiki/INI_file>`_: ``name = value``.  You can
+<https://en.wikipedia.org/wiki/INI_file>`_: ``name = value``.  You can
 extend the value by indenting subsequent lines.  ``#`` is a comment.
 
 Typically you have one or two sections, named "main": an application
@@ -120,9 +120,9 @@ section (``[app:main]``) and a server section (``[server:main]``).
 ``[composite:...]`` signifies something that dispatches to multiple
 applications (example below).
 
-Here's a typical configuration file that also shows off mounting
-multiple applications using `paste.urlmap
-<http://pythonpaste.org/module-paste.urlmap.html>`_::
+Here's a typical configuration file that also shows off mounting multiple applications:
+
+.. code-block:: ini
 
     [composite:main]
     use = egg:Paste#urlmap
@@ -149,7 +149,9 @@ multiple applications using `paste.urlmap
     use = call:mywiki.main:application
     database = sqlite:/home/me/wiki.db
 
-I'll explain each section in detail now::
+I'll explain each section in detail now:
+
+.. code-block:: ini
 
     [composite:main]
     use = egg:Paste#urlmap
@@ -165,7 +167,9 @@ path prefix to map your request to another application.  These are
 the applications like "home", "blog", "wiki" and "config:cms.ini".  The last
 one just refers to another file ``cms.ini`` in the same directory.
 
-Next up::
+Next up:
+
+.. code-block:: ini
 
     [app:home]
     use = egg:Paste#static
@@ -180,7 +184,9 @@ the directory containing the configuration file; you should use that
 in lieu of relative filenames (which depend on the current directory,
 which can change depending how the server is run).
 
-Then::
+Then:
+
+.. code-block:: ini
 
     [filter-app:blog]
     use = egg:Authentication#auth
@@ -202,7 +208,9 @@ That last section is just a reference to an application that you
 probably installed with ``pip install BlogApp``, and one bit of
 configuration you passed to it (``database``).
 
-Lastly::
+Lastly:
+
+.. code-block:: ini
 
     [app:wiki]
     use = call:mywiki.main:application
@@ -221,12 +229,14 @@ Basic Usage
 -----------
 
 The basic way you'll use Paste Deployment is to load `WSGI
-<http://www.python.org/peps/pep-3333.html>`_ applications.  Many
+<https://www.python.org/dev/peps/pep-3333/>`_ applications.  Many
 Python frameworks now support WSGI, so applications written for these
 frameworks should be usable.
 
 The primary function is ``paste.deploy.loadapp``.  This loads an
-application given a URI.  You can use it like::
+application given a URI.  You can use it like:
+
+.. code-block:: ini
 
     from paste.deploy import loadapp
     wsgi_app = loadapp('config:/path/to/config.ini')
@@ -280,7 +290,9 @@ Each section name defining an application should be prefixed with
 would go in ``[app:main]`` or just ``[app]``.
 
 There's two ways to indicate the Python code for the application.  The
-first is to refer to another URI or name::
+first is to refer to another URI or name:
+
+.. code-block:: ini
 
     [app:myapp]
     use = config:another_config_file.ini#app_name
@@ -302,7 +314,9 @@ another location.  However, in addition to loading the application
 from that location, you can also add or change the configuration.
 
 The other way to define an application is to point exactly to some
-Python code::
+Python code:
+
+.. code-block:: ini
 
     [app:myapp]
     paste.app_factory = myapp.modulename:app_factory
@@ -319,14 +333,18 @@ Configuration
 
 Configuration is done through keys besides ``use`` (or the protocol
 names).  Any other keys found in the section will be passed as keyword
-arguments to the factory.  This might look like::
+arguments to the factory.  This might look like:
+
+.. code-block:: ini
 
     [app:blog]
     use = egg:MyBlog
     database = mysql://localhost/blogdb
     blogname = This Is My Blog!
 
-You can override these in other sections, like::
+You can override these in other sections, like:
+
+.. code-block:: ini
 
     [app:otherblog]
     use = blog
@@ -354,7 +372,9 @@ configuration is passed in.
 
 Global configuration to apply to every application defined in a file
 should go in a special section named ``[DEFAULT]``.  You can override
-global configuration locally like::
+global configuration locally like:
+
+.. code-block:: ini
 
     [DEFAULT]
     admin_email = webmaster@example.com
@@ -371,7 +391,9 @@ Composite Applications
 "Composite" applications are things that act like applications, but
 are made up of other applications.  One example would be a URL mapper,
 where you mount applications at different URL paths.  This might look
-like::
+like:
+
+.. code-block:: ini
 
     [composite:main]
     use = egg:Paste#urlmap
@@ -404,7 +426,9 @@ Filter Composition
 There are several ways to apply filters to applications.  It mostly
 depends on how many filters, and in what order you want to apply them.
 
-The first way is to use the ``filter-with`` setting, like::
+The first way is to use the ``filter-with`` setting, like:
+
+.. code-block:: ini
 
     [app:main]
     use = egg:MyEgg
@@ -426,13 +450,15 @@ points to the application to apply the filter to.
 ``pipeline:`` is used when you need apply a number of filters.  It
 takes *one* configuration key ``pipeline`` (plus any global
 configuration overrides you want).  ``pipeline`` is a list of filters
-ended by an application, like::
+ended by an application, like:
+
+.. code-block:: ini
 
     [pipeline:main]
     pipeline = filter1 egg:FilterEgg#filter2 filter3 app
 
     [filter:filter1]
-    ...
+    # ...
 
 Getting Configuration
 ~~~~~~~~~~~~~~~~~~~~~
@@ -454,13 +480,15 @@ are a distribution and installation format produced by `setuptools
 normal Python package (among other things).
 
 You don't need to understand a whole lot about Eggs to use them.  If
-you have a `distutils
-<http://python.org/doc/current/lib/module-distutils.html>`_
-``setup.py`` script, just change::
+you have a :mod:`<python:distutils>` ``setup.py`` script, just change:
+
+.. code-block:: python
 
     from distutils.core import setup
 
-to::
+to:
+
+.. code-block:: python
 
     from setuptools import setup
 
@@ -481,11 +509,13 @@ more about the protocols later_.
 .. _later: `Defining Factories`_
 
 The important part here is how we define entry points.  You'll add an
-argument to ``setup()`` like::
+argument to ``setup()`` like:
+
+.. code-block:: python
 
     setup(
         name='MyApp',
-        ...
+        # ...
         entry_points={
             'paste.app_factory': [
                 'main=myapp.mymodule:app_factory',
@@ -518,7 +548,9 @@ function, method, or class).
 ``paste.app_factory``
 ~~~~~~~~~~~~~~~~~~~~~~
 
-The application is the most common.  You define one like::
+The application is the most common.  You define one like:
+
+.. code-block:: python
 
     def app_factory(global_config, **local_conf):
         return wsgi_app
@@ -529,7 +561,9 @@ passed as keyword arguments.  The function returns a WSGI application.
 ``paste.composite_factory``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Composites are just slightly more complex::
+Composites are just slightly more complex:
+
+.. code-block:: python
 
     def composite_factory(loader, global_config, **local_conf):
         return wsgi_app
@@ -540,7 +574,9 @@ application with the given name.  ``get_filter`` and ``get_server``
 work the same way.
 
 A more interesting example might be a composite factory that does
-something.  For instance, consider a "pipeline" application::
+something.  For instance, consider a "pipeline" application:
+
+.. code-block:: python
 
     def pipeline_factory(loader, global_config, pipeline):
         # space-separated list of filter and app names:
@@ -552,7 +588,9 @@ something.  For instance, consider a "pipeline" application::
             app = filter(app)
         return app
 
-Then we use it like::
+Then we use it like:
+
+.. code-block:: ini
 
     [composite:main]
     use = <pipeline_factory_uri>
@@ -574,7 +612,9 @@ application as the only argument, and return a "filtered" version of
 that application.
 
 Here's an example of a filter that checks that the ``REMOTE_USER`` CGI
-variable is set, creating a really simple authentication filter::
+variable is set, creating a really simple authentication filter:
+
+.. code-block:: python
 
     def auth_filter_factory(global_conf, req_usernames):
         # space-separated list of usernames:
@@ -600,11 +640,13 @@ variable is set, creating a really simple authentication filter::
 
 This is very similar to ``paste.filter_factory``, except that it also
 takes a ``wsgi_app`` argument, and returns a WSGI application.  So if
-you changed the above example to::
+you changed the above example to:
+
+.. code-block:: python
 
     class AuthFilter(object):
         def __init__(self, app, global_conf, req_usernames):
-            ....
+            # ...
 
 Then ``AuthFilter`` would serve as a filter_app_factory
 (``req_usernames`` is a required local configuration key in this
@@ -619,7 +661,9 @@ a server.
 A server is a callable that takes a single argument, a WSGI
 application.  It then serves the application.
 
-An example might look like::
+An example might look like:
+
+.. code-block:: python
 
     def server_factory(global_conf, host, port):
         port = int(port)
@@ -660,12 +704,14 @@ Outstanding Issues
   translate objects into their proper types.
 
 * Some short-form for a filter/app, where the filter refers to the
-  "next app".  Maybe like::
+  "next app".  Maybe like:
+
+.. code-block:: ini
 
     [app-filter:app_name]
     use = egg:...
     next = next_app
 
     [app:next_app]
-    ...
+    # ...
 
diff --git a/docs/modules/config.txt b/docs/modules/config.rst
index 9d8f894..9d8f894 100644
--- a/docs/modules/config.txt
+++ b/docs/modules/config.rst
diff --git a/docs/modules/converters.txt b/docs/modules/converters.rst
index 4948104..4948104 100644
--- a/docs/modules/converters.txt
+++ b/docs/modules/converters.rst
diff --git a/docs/modules/loadwsgi.txt b/docs/modules/loadwsgi.rst
index feebf28..feebf28 100644
--- a/docs/modules/loadwsgi.txt
+++ b/docs/modules/loadwsgi.rst
diff --git a/docs/news.txt b/docs/news.rst
index bc1e987..0f4e309 100644
--- a/docs/news.txt
+++ b/docs/news.rst
@@ -160,13 +160,9 @@ Released 26 August 2004
 * Removed the ``1`` from all the protocol names (e.g.,
   ``paste.app_factory1`` is not ``paste.app_factory``).
 
-* Added ``filter-app:`` and ``pipeline:`` sections.  `Docs
-  <paste-deploy.html#filter-composition>`__.
+* Added ``filter-app:`` and ``pipeline:`` sections.
 
-* Added ``paste.filter_app_factory1`` (`doc
-  <paste-deploy.html#paste-filter-app-factory1>`__) and
-  ``paste.server_runner1`` (`doc
-  <paste-deploy.html#paste-server-runner1>`__) protocols.
+* Added ``paste.filter_app_factory1`` and ``paste.server_runner1`` protocols.
 
 * Added ``paste.deploy.converters`` module for handling the
   string values that are common with this system.
diff --git a/regen-docs b/regen-docs
deleted file mode 100755
index f8dad75..0000000
--- a/regen-docs
+++ /dev/null
@@ -1,9 +0,0 @@
-#!/bin/sh
-
-mkdir -p docs/_static docs/_build
-sphinx-build -E -b html docs/ docs/_build || exit 1
-if [ "$1" = "publish" ] ; then
-  cd docs/
-  echo "Uploading files..."
-  scp -r _build/* ianb@webwareforpython.org:/home/paste/htdocs/deploy/
-fi
diff --git a/rtd.txt b/rtd.txt
new file mode 100644
index 0000000..142b6ca
--- /dev/null
+++ b/rtd.txt
@@ -0,0 +1 @@
+-e .[docs]
diff --git a/tox.ini b/tox.ini
index 9800db2..7819491 100644
--- a/tox.ini
+++ b/tox.ini
@@ -1,5 +1,6 @@
 [tox]
-envlist = py27, py34, py35, py36, py37, pypy, pypy3
+envlist = py27, py34, py35, py36, py37, pypy, pypy3,
+    docs
 
 [testenv]
 deps =
@@ -9,3 +10,12 @@ deps =
     pytest-cov
 commands =
     py.test --cov=paste/deploy --cov-report=xml --cov-report=html --cov-report=term-missing {posargs}
+
+[testenv:docs]
+# pin to 3.5 to match what RTD uses
+basepython = python3.5
+whitelist_externals = make
+commands =
+    make -C docs html epub BUILDDIR={envdir} "SPHINXOPTS=-W -E"
+extras =
+    docs