Merge branch 'master' into deprecate-pickle-sessions

11 files changed, 91 insertions, 51 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 54b8beba4..926584de0 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -62,6 +62,10 @@ Features
   information about this feature.
   See https://github.com/Pylons/pyramid/pull/3353
 
+- Add a ``registry`` argument to ``pyramid.renderers.get_renderer``
+  to allow users to avoid threadlocals during renderer lookup.
+  See https://github.com/Pylons/pyramid/pull/3358
+
 Bug Fixes
 ---------
 
@@ -130,6 +134,10 @@ Backward Incompatibilities
 Documentation Changes
 ---------------------
 
+- Ad support for Read The Docs Ethical Ads.
+  https://github.com/Pylons/pyramid/pull/3360
+  https://docs.readthedocs.io/en/latest/advertising/ethical-advertising.html
+
 - Add support for alembic to the pyramid-cookiecutter-alchemy cookiecutter
   and update the wiki2 tutorial to explain how it works.
   See https://github.com/Pylons/pyramid/pull/3307 and
diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt
index 0c18d600f..80b43c8ec 100644
--- a/CONTRIBUTORS.txt
+++ b/CONTRIBUTORS.txt
@@ -331,3 +331,4 @@ Contributors
 
 - Kuzma Leshakov, 2018/09/07
 
+- Colin Dunklau, 2018/09/19
diff --git a/COPYRIGHT.txt b/COPYRIGHT.txt
index 645160fa5..6e23cb876 100644
--- a/COPYRIGHT.txt
+++ b/COPYRIGHT.txt
@@ -1,4 +1,4 @@
-Copyright (c) 2008-2011 Agendaless Consulting and Contributors.
+Copyright (c) 2008-2018 Agendaless Consulting and Contributors.
 (http://www.agendaless.com), All Rights Reserved
 
 Portions (c) Zope Foundation and contributors (http://www.zope.org/).
diff --git a/HACKING.txt b/HACKING.txt
index 3a7774781..fdfee58d6 100644
--- a/HACKING.txt
+++ b/HACKING.txt
@@ -8,9 +8,13 @@ Using a Development Checkout
 ----------------------------
 
 You'll have to create a development environment to hack on Pyramid, using a
-Pyramid checkout.  You can either do this by hand, or if you have ``tox``
-installed (it's on PyPI), you can use ``tox`` to set up a working development
-environment.  Each installation method is described below.
+Pyramid checkout.  You can either do this by hand, or if you have `tox`
+installed, you can use it to set up a working development environment.
+
+tox docs: http://tox.readthedocs.org/en/latest/
+tox on PyPI: https://pypi.org/project/tox/
+
+Each installation method is described below.
 
 
 By Hand
@@ -46,20 +50,20 @@ repo, from which you can submit a pull request.
     $ cd ~/hack-on-pyramid
     $ python3 -m venv env
 
-  From here on in within these instructions, the ``~/hack-on-pyramid/env``
-  virtual environment you created above will be referred to as ``$VENV``.
+  From here on in within these instructions, the `~/hack-on-pyramid/env`
+  virtual environment you created above will be referred to as `$VENV`.
   To use the instructions in the steps that follow literally, use the
-  ``export VENV=~/hack-on-pyramid/env`` command.
+  `export VENV=~/hack-on-pyramid/env` command.
 
 - Install Pyramid from the checkout into the virtual environment, where the
-  current working directory is the ``pyramid`` checkout directory. We will
+  current working directory is the `pyramid` checkout directory. We will
   install Pyramid in editable (development) mode as well as its testing
   requirements.
 
     $ cd ~/hack-on-pyramid
     $ $VENV/bin/pip install -e ".[testing,docs]"
 
-- Optionally create a new Pyramid project using ``pcreate``:
+- Optionally create a new Pyramid project using `pcreate`:
 
     $ cd $VENV
     $ bin/pcreate -s starter starter
@@ -70,13 +74,13 @@ repo, from which you can submit a pull request.
     $ $VENV/bin/pip install -e .
 
 
-Using ``Tox``
-+++++++++++++
+Using `Tox`
++++++++++++
 
-Alternatively, if you already have ``tox`` installed, there is an easier
+Alternatively, if you already have `tox` installed, there is an easier
 way to get going.
 
-- Create a new directory somewhere and ``cd`` to it:
+- Create a new directory somewhere and `cd` to it:
 
     $ mkdir ~/hack-on-pyramid
     $ cd ~/hack-on-pyramid
@@ -89,16 +93,15 @@ way to get going.
 
 Since Pyramid is a framework and not an application, it can be convenient to
 work against a sample application, preferably in its own virtual environment. A
-quick way to achieve this is to use `tox
-<http://tox.readthedocs.org/en/latest/>`_ with a custom configuration file
+quick way to achieve this is to use `tox` with a custom configuration file
 that is part of the checkout:
 
     $ tox -c hacking-tox.ini
 
-This will create a python-2.7 based virtual environment named ``env27``
-(Pyramid's ``.gitconfig` ignores all top-level folders that start with ``env``
+This will create a python-2.7 based virtual environment named `env27`
+(Pyramid's `.gitconfig` ignores all top-level folders that start with `env`
 specifically in our use case), and inside that a simple pyramid application
-named ``hacking`` that you can then fire up like so:
+named `hacking` that you can then fire up like so:
 
     $ cd env27/hacking
     $ ../bin/pip install -e ".[testing,docs]"
@@ -111,7 +114,7 @@ Adding Features
 In order to add a feature to Pyramid:
 
 - The feature must be documented in both the API and narrative documentation
-  (in ``docs/``).
+  (in `docs/`).
 
 - The feature must work fully on the following CPython versions: 2.7, 3.4, 3.5,
   3.6, and 3.7 on both UNIX and Windows.
@@ -127,7 +130,7 @@ In order to add a feature to Pyramid:
 The above requirements are relaxed for scaffolding dependencies.  If a scaffold
 has an install-time dependency on something that doesn't work on a particular
 platform, that caveat should be spelled out clearly in *its* documentation
-(within its ``docs/`` directory).
+(within its `docs/` directory).
 
 
 Coding Style
@@ -147,11 +150,11 @@ Running Tests
 
 - To run all tests for Pyramid on a single Python version from your development
   virtual environment (See *Using a Development Checkout* above), run
-  ``nosetests``:
+  `nosetests`:
 
     $ $VENV/bin/nosetests
 
-- To run individual tests (i.e., during development), you can use ``nosetests``
+- To run individual tests (i.e., during development), you can use `nosetests`
   syntax as follows:
 
     # run a single test
@@ -160,14 +163,14 @@ Running Tests
     # run all tests in a class
     $ $VENV/bin/nosetests pyramid.tests.test_module:ClassName
 
-  Optionally you can install a nose plugin, `nose-selecttests
-  <https://pypi.org/project/nose-selecttests/>`_, and use a regular
-  expression with the ``-t`` parameter to run tests.
+  Optionally you can install a nose plugin, `nose-selecttests`
+  ( https://pypi.org/project/nose-selecttests/ ), and use a regular
+  expression with the `-t` parameter to run tests.
 
     # run a single test
     $ $VENV/bin/nosetests -t test_mytestname
 
-- The ``tox.ini`` uses ``nose`` and ``coverage``. As such ``tox`` may be used
+- The `tox.ini` uses `nose` and `coverage`. As such `tox` may be used
   to run groups of tests or only a specific version of Python. For example, the
   following command will run tests on Python 2.7 only without coverage:
 
@@ -178,22 +181,21 @@ Running Tests
 
     $ tox -e py2-cover,py3-cover,coverage
 
-- To run the full set of Pyramid tests on all platforms, install `tox
-  <http://codespeak.net/~hpk/tox/>`_ into a system Python. The ``tox`` console
-  script will be installed into the scripts location for that Python. While
-  ``cd``'ed to the Pyramid checkout root directory (it contains ``tox.ini``),
-  invoke the ``tox`` console script. This will read the ``tox.ini`` file and
-  execute the tests on multiple Python versions and platforms. While it runs,
-  it creates a virtual environment for each version/platform combination.  For
-  example:
+- To run the full set of Pyramid tests on all platforms, install `tox` into a
+  system Python. The `tox` console script will be installed into the scripts
+  location for that Python. While `cd`'ed to the Pyramid checkout root
+  directory (it contains `tox.ini`), invoke the `tox` console script. This
+  will read the `tox.ini` file and execute the tests on multiple Python
+  versions and platforms. While it runs, it creates a virtual environment
+  for each version/platform combination.  For example:
 
     $ sudo /usr/bin/pip install tox
     $ cd ~/hack-on-pyramid/
     $ /usr/bin/tox
 
-- The tests can also be run using `pytest <http://pytest.org/>`_. This is
+- The tests can also be run using `pytest` ( http://pytest.org/ ). This is
   intended as a convenience for people who are more used to or fond of
-  ``pytest``. Run the tests like so:
+  `pytest`. Run the tests like so:
 
     $ $VENV/bin/pip install pytest
     $ $VENV/bin/py.test --strict pyramid/
@@ -218,8 +220,8 @@ Test Coverage
 -------------
 
 - The codebase *must* have 100% test statement coverage after each commit.  You
-  can test coverage via ``./coverage.sh`` (which itself just executes ``tox
-  -epy2-cover,py3-cover,coverage``).
+  can test coverage via `./coverage.sh` (which itself just executes `tox
+  -epy2-cover,py3-cover,coverage`).
 
 
 Documentation Coverage and Building HTML Documentation
@@ -230,19 +232,19 @@ documentation in this package which references that API or behavior must be
 changed to reflect the bug fix, ideally in the same commit that fixes the bug
 or adds the feature.  To build and review docs, use the following steps.
 
-1. In the main Pyramid checkout directory, run ``./builddocs.sh`` (which just
-   turns around and runs ``tox -e docs``):
+1. In the main Pyramid checkout directory, run `./builddocs.sh` (which just
+   turns around and runs `tox -e docs`):
 
      $ ./builddocs.sh
 
-2. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
+2. Open the `docs/_build/html/index.html` file to see the resulting HTML
    rendering.
 
 
 Change Log
 ----------
 
-- Feature additions and bugfixes must be added to the ``CHANGES.rst``
+- Feature additions and bugfixes must be added to the `CHANGES.rst`
   file in the prevailing style.  Changelog entries should be long and
   descriptive, not cryptic.  Other developers should be able to know
   what your changelog entry means.
diff --git a/docs/conf.py b/docs/conf.py
index 8fe7108ff..6e3d41240 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -161,6 +161,15 @@ html_theme_options = dict(
     outdated='false',
     )
 
+# Control display of sidebars
+html_sidebars = {'**': [
+    'localtoc.html',
+    'ethicalads.html',
+    'relations.html',
+    'sourcelink.html',
+    'searchbox.html',
+]}
+
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 html_title = 'The Pyramid Web Framework v%s' % release
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 587e7c63e..ec4cffef2 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -343,7 +343,7 @@ Glossary
      full-featured Python web framework.
 
    Grok
-     `A web framework based on Zope 3 <http://grok.zope.org>`_.
+     `A web framework based on Zope 3 <https://web.archive.org/web/20180615015013/http://grok.zope.org>`_.
 
    Django
      `A full-featured Python web framework <https://www.djangoproject.com/>`_.
@@ -1083,7 +1083,7 @@ Glossary
 
    Green Unicorn
       Aka ``gunicorn``, a fast :term:`WSGI` server that runs on Unix under
-      Python 2.6+ or Python 3.1+.  See http://gunicorn.org/ for detailed 
+      Python 2.6+ or Python 3.1+.  See https://gunicorn.org/ for detailed
       information.
 
    predicate factory
diff --git a/docs/index.rst b/docs/index.rst
index 76d23b4f4..19cff9414 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -66,7 +66,7 @@ Official tutorials provide a quick overview of :app:`Pyramid`'s features in more
 Support and Development
 =======================
 
-The `Pyramid website <https://trypyramid.com/resources.html>`_ is the main
+The `Pyramid website <https://trypyramid.com/documentation.html>`_ is the main
 entry point to :app:`Pyramid` web framework resources for support and
 development information.
 
diff --git a/docs/narr/introduction.rst b/docs/narr/introduction.rst
index 3ee6b5367..9293386f2 100644
--- a/docs/narr/introduction.rst
+++ b/docs/narr/introduction.rst
@@ -52,7 +52,7 @@ Modern
 Tested
 ~~~~~~
 
-Untested code is broken by design. The :app:`Pyramid` community has a strong testing culture and our framework reflects that. Every release of :app:`Pyramid` has 100% statement coverage (as measured by `coverage <https://coverage.readthedocs.io/en/latest/>`_) and 95% decision/condition coverage. (as measured by `instrumental <https://instrumental.readthedocs.io/en/latest/intro.html>`_) It is automatically tested using `Travis <https://travis-ci.org/Pylons/pyramid>`_ and `Jenkins <http://jenkins.pylonsproject.org/job/pyramid/>`_ on supported versions of Python after each commit to its GitHub repository. `Official Pyramid add-ons <https://trypyramid.com/resources-extending-pyramid.html>`_ are held to a similar testing standard.
+Untested code is broken by design. The :app:`Pyramid` community has a strong testing culture and our framework reflects that. Every release of :app:`Pyramid` has 100% statement coverage (as measured by `coverage <https://coverage.readthedocs.io/en/latest/>`_) and 95% decision/condition coverage. (as measured by `instrumental <https://instrumental.readthedocs.io/en/latest/intro.html>`_) It is automatically tested using `Travis <https://travis-ci.org/Pylons/pyramid>`_ and `Jenkins <http://jenkins.pylonsproject.org/job/pyramid/>`_ on supported versions of Python after each commit to its GitHub repository. `Official Pyramid add-ons <https://trypyramid.com/extending-pyramid.html>`_ are held to a similar testing standard.
 
 We still find bugs in :app:`Pyramid`, but we've noticed we find a lot fewer of them while working on projects with a solid testing regime.
 
@@ -173,7 +173,7 @@ Supported :app:`Pyramid` add-ons are held to the same demanding standards as the
 
 .. seealso::
 
-    See also https://trypyramid.com/resources-extending-pyramid.html
+    See also https://trypyramid.com/extending-pyramid.html
 
 Write your views, *your* way
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/pyramid/renderers.py b/pyramid/renderers.py
index 6019f50fb..d1c85b371 100644
--- a/pyramid/renderers.py
+++ b/pyramid/renderers.py
@@ -147,7 +147,7 @@ def render_to_response(renderer_name,
 
     return result
 
-def get_renderer(renderer_name, package=None):
+def get_renderer(renderer_name, package=None, registry=None):
     """ Return the renderer object for the renderer ``renderer_name``.
 
     You may supply a relative asset spec as ``renderer_name``.  If
@@ -157,10 +157,16 @@ def get_renderer(renderer_name, package=None):
     asset specification ``renderer_name``.  If ``package`` is ``None``
     (the default), the package name of the *caller* of this function
     will be used as the package.
+
+    You may directly supply an :term:`application registry` using the
+    ``registry`` argument, and it will be used to look up the renderer.
+    Otherwise, the current thread-local registry (obtained via
+    :func:`~pyramid.threadlocal.get_current_registry`) will be used.
     """
     if package is None:
         package = caller_package()
-    helper = RendererHelper(name=renderer_name, package=package)
+    helper = RendererHelper(name=renderer_name, package=package,
+                            registry=registry)
     return helper.renderer
 
 # concrete renderer factory implementations (also API)
diff --git a/pyramid/tests/test_renderers.py b/pyramid/tests/test_renderers.py
index 86d8b582a..a2f7bf8c2 100644
--- a/pyramid/tests/test_renderers.py
+++ b/pyramid/tests/test_renderers.py
@@ -624,6 +624,20 @@ class Test_get_renderer(unittest.TestCase):
         result = self._callFUT('abc/def.pt', package=pyramid.tests)
         self.assertEqual(result, renderer)
 
+    def test_it_with_registry(self):
+        renderer = self.config.testing_add_renderer(
+            'pyramid.tests:abc/def.pt')
+        result = self._callFUT('abc/def.pt', registry=self.config.registry)
+        self.assertEqual(result, renderer)
+
+    def test_it_with_isolated_registry(self):
+        from pyramid.config import Configurator
+        isolated_config = Configurator()
+        renderer = isolated_config.testing_add_renderer(
+            'pyramid.tests:abc/def.pt')
+        result = self._callFUT('abc/def.pt', registry=isolated_config.registry)
+        self.assertEqual(result, renderer)
+
 class TestJSONP(unittest.TestCase):
     def _makeOne(self, param_name='callback'):
         from pyramid.renderers import JSONP
diff --git a/setup.py b/setup.py
index 56f9e30d1..d3d453a0d 100644
--- a/setup.py
+++ b/setup.py
@@ -41,9 +41,9 @@ tests_require = [
 
 
 docs_extras = [
-    'Sphinx >= 1.7.4,<=1.7.9',
+    'Sphinx >= 1.8.1',
     'docutils',
-    'pylons-sphinx-themes',
+    'pylons-sphinx-themes >= 1.0.8',
     'pylons_sphinx_latesturl',
     'repoze.sphinx.autointerface',
     'sphinxcontrib-autoprogram',