Merge pull request #3330 from stevepiercy/docs-code-style

Docs code style

24 files changed, 246 insertions, 247 deletions

diff --git a/docs/quick_tutorial/authentication.rst b/docs/quick_tutorial/authentication.rst
index 529f51ddd..eb9b6b395 100644
--- a/docs/quick_tutorial/authentication.rst
+++ b/docs/quick_tutorial/authentication.rst
@@ -33,7 +33,7 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes authentication; cd authentication
+       cd ..; cp -r view_classes authentication; cd authentication
 
 #. Add ``bcrypt`` as a dependency in ``authentication/setup.py``:
 
@@ -46,7 +46,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/pip install -e .
+       $VENV/bin/pip install -e .
 
 #. Put the security hash in the ``authentication/development.ini``
    configuration file as ``tutorial.secret`` instead of putting it in the code:
@@ -88,7 +88,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in a browser.
 
diff --git a/docs/quick_tutorial/authorization.rst b/docs/quick_tutorial/authorization.rst
index 58c1d2582..e80f88c51 100644
--- a/docs/quick_tutorial/authorization.rst
+++ b/docs/quick_tutorial/authorization.rst
@@ -41,31 +41,31 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r authentication authorization; cd authorization
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r authentication authorization; cd authorization
+       $VENV/bin/pip install -e .
 
 #. Start by changing ``authorization/tutorial/__init__.py`` to specify a root
    factory to the :term:`configurator`:
 
    .. literalinclude:: authorization/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. That means we need to implement ``authorization/tutorial/resources.py``:
 
    .. literalinclude:: authorization/tutorial/resources.py
-    :linenos:
+       :linenos:
 
 #. Change ``authorization/tutorial/views.py`` to require the ``edit``
    permission on the ``hello`` view and implement the forbidden view:
 
    .. literalinclude:: authorization/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in a browser.
 
diff --git a/docs/quick_tutorial/cookiecutters.rst b/docs/quick_tutorial/cookiecutters.rst
index f8568206d..045808884 100644
--- a/docs/quick_tutorial/cookiecutters.rst
+++ b/docs/quick_tutorial/cookiecutters.rst
@@ -28,7 +28,7 @@ Steps
 
     .. code-block:: bash
 
-        $ $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master
+        $VENV/bin/cookiecutter gh:Pylons/pyramid-cookiecutter-starter --checkout master
 
     If prompted for the first item, accept the default ``yes`` by hitting return.
 
@@ -49,20 +49,20 @@ Steps
     .. code-block:: bash
 
         # Change directory into your newly created project.
-        $ cd cc_starter
+        cd cc_starter
         # Create a new virtual environment...
-        $ python3 -m venv env
+        python3 -m venv env
         # ...where we upgrade packaging tools...
-        $ env/bin/pip install --upgrade pip setuptools
+        env/bin/pip install --upgrade pip setuptools
         # ...and into which we install our project.
-        $ env/bin/pip install -e .
+        env/bin/pip install -e .
 
 #.  Start up the application by pointing :app:`Pyramid`'s ``pserve`` command at the
     project's (generated) configuration file:
 
     .. code-block:: bash
 
-        $ env/bin/pserve development.ini --reload
+        env/bin/pserve development.ini --reload
 
     On start up, ``pserve`` logs some output:
 
diff --git a/docs/quick_tutorial/databases.rst b/docs/quick_tutorial/databases.rst
index 87f2703c7..7d10f2470 100644
--- a/docs/quick_tutorial/databases.rst
+++ b/docs/quick_tutorial/databases.rst
@@ -45,7 +45,7 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r forms databases; cd databases
+       cd ..; cp -r forms databases; cd databases
 
 #. We need to add some dependencies in ``databases/setup.py`` as well as an
    "entry point" for the command-line script:
@@ -62,85 +62,85 @@ Steps
    new pieces:
 
    .. literalinclude:: databases/development.ini
-    :language: ini
+       :language: ini
 
 #. This engine configuration now needs to be read into the application through
    changes in ``databases/tutorial/__init__.py``:
 
    .. literalinclude:: databases/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Make a command-line script at ``databases/tutorial/initialize_db.py`` to
    initialize the database:
 
    .. literalinclude:: databases/tutorial/initialize_db.py
-    :linenos:
+       :linenos:
 
 #. Since ``setup.py`` changed, we now run it:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pip install -e .
+       $VENV/bin/pip install -e .
 
 #. The script references some models in ``databases/tutorial/models.py``:
 
    .. literalinclude:: databases/tutorial/models.py
-    :linenos:
+       :linenos:
 
 #. Let's run this console script, thus producing our database and table:
 
    .. code-block:: bash
 
-    $ $VENV/bin/initialize_tutorial_db development.ini
-
-    2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
-    2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-    2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
-    2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-    2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages")
-    2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-    2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread]
-    CREATE TABLE wikipages (
-            uid INTEGER NOT NULL,
-            title TEXT,
-            body TEXT,
-            PRIMARY KEY (uid),
-            UNIQUE (title)
-    )
-
-
-    2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
-    2016-04-16 13:01:33,059 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
-    2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit)
-    2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?)
-    2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>')
-    2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
+       $VENV/bin/initialize_tutorial_db development.ini
+
+       2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test plain returns' AS VARCHAR(60)) AS anon_1
+       2016-04-16 13:01:33,055 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+       2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] SELECT CAST('test unicode returns' AS VARCHAR(60)) AS anon_1
+       2016-04-16 13:01:33,056 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+       2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] PRAGMA table_info("wikipages")
+       2016-04-16 13:01:33,057 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+       2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread]
+       CREATE TABLE wikipages (
+               uid INTEGER NOT NULL,
+               title TEXT,
+               body TEXT,
+               PRIMARY KEY (uid),
+               UNIQUE (title)
+       )
+
+
+       2016-04-16 13:01:33,058 INFO  [sqlalchemy.engine.base.Engine][MainThread] ()
+       2016-04-16 13:01:33,059 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
+       2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] BEGIN (implicit)
+       2016-04-16 13:01:33,062 INFO  [sqlalchemy.engine.base.Engine][MainThread] INSERT INTO wikipages (title, body) VALUES (?, ?)
+       2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] ('Root', '<p>Root</p>')
+       2016-04-16 13:01:33,063 INFO  [sqlalchemy.engine.base.Engine][MainThread] COMMIT
 
 #. With our data now driven by SQLAlchemy queries, we need to update our
    ``databases/tutorial/views.py``:
 
    .. literalinclude:: databases/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Our tests in ``databases/tutorial/tests.py`` changed to include SQLAlchemy
    bootstrapping:
 
    .. literalinclude:: databases/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Run the tests in your package using ``py.test``:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ..
-    2 passed in 1.41 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ..
+       2 passed in 1.41 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in a browser.
 
diff --git a/docs/quick_tutorial/debugtoolbar.rst b/docs/quick_tutorial/debugtoolbar.rst
index 4402fcdbd..b49dd1f97 100644
--- a/docs/quick_tutorial/debugtoolbar.rst
+++ b/docs/quick_tutorial/debugtoolbar.rst
@@ -37,22 +37,22 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r ini debugtoolbar; cd debugtoolbar
-    $ $VENV/bin/pip install -e .
-    $ $VENV/bin/pip install pyramid_debugtoolbar
+       cd ..; cp -r ini debugtoolbar; cd debugtoolbar
+       $VENV/bin/pip install -e .
+       $VENV/bin/pip install pyramid_debugtoolbar
 
 #. Our ``debugtoolbar/development.ini`` gets a configuration entry for
    ``pyramid.includes``:
 
    .. literalinclude:: debugtoolbar/development.ini
-    :language: ini
-    :linenos:
+       :language: ini
+       :linenos:
 
 #. Run the WSGI application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in your browser. See the handy
    toolbar on the right.
@@ -100,15 +100,15 @@ Extra credit
 
    .. code-block:: python
 
-     def hello_world(request):
-         return Response('<body><h1>Hello World!</h1></body>')
+       def hello_world(request):
+           return Response('<body><h1>Hello World!</h1></body>')
 
    to:
 
    .. code-block:: python
 
-    def hello_world(request):
-        return xResponse('<body><h1>Hello World!</h1></body>')
+       def hello_world(request):
+           return xResponse('<body><h1>Hello World!</h1></body>')
 
    Save, and visit http://localhost:6543/ again. Notice the nice traceback
    display. On the lowest line, click the "screen" icon to the right, and try
diff --git a/docs/quick_tutorial/forms.rst b/docs/quick_tutorial/forms.rst
index 45eb05a8f..be745764b 100644
--- a/docs/quick_tutorial/forms.rst
+++ b/docs/quick_tutorial/forms.rst
@@ -35,71 +35,71 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes forms; cd forms
+       cd ..; cp -r view_classes forms; cd forms
 
 #. Let's edit ``forms/setup.py`` to declare a dependency on Deform (which then
    pulls in Colander as a dependency:
 
    .. literalinclude:: forms/setup.py
-    :emphasize-lines: 4
-    :linenos:
+       :emphasize-lines: 4
+       :linenos:
 
 #. We can now install our project in development mode:
 
    .. code-block:: bash
 
-      $ $VENV/bin/pip install -e .
+       $VENV/bin/pip install -e .
 
 #. Register a static view in ``forms/tutorial/__init__.py`` for Deform's CSS,
    JavaScript, etc., as well as our demo wiki page's views:
 
    .. literalinclude:: forms/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Implement the new views, as well as the form schemas and some dummy data, in
    ``forms/tutorial/views.py``:
 
    .. literalinclude:: forms/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. A template for the top of the "wiki" in ``forms/tutorial/wiki_view.pt``:
 
    .. literalinclude:: forms/tutorial/wiki_view.pt
-    :language: html
-    :linenos:
+       :language: html
+       :linenos:
 
 #. Another template for adding/editing in
    ``forms/tutorial/wikipage_addedit.pt``:
 
    .. literalinclude:: forms/tutorial/wikipage_addedit.pt
-    :language: html
-    :linenos:
+       :language: html
+       :linenos:
 
 #. Add a template at ``forms/tutorial/wikipage_view.pt`` for viewing a wiki
    page:
 
    .. literalinclude:: forms/tutorial/wikipage_view.pt
-    :language: html
-    :linenos:
+       :language: html
+       :linenos:
 
 #. Our tests in ``forms/tutorial/tests.py`` don't run, so let's modify them:
 
    .. literalinclude:: forms/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ..
-    2 passed in 0.45 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ..
+       2 passed in 0.45 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in a browser.
 
diff --git a/docs/quick_tutorial/functional_testing.rst b/docs/quick_tutorial/functional_testing.rst
index 518e3d67d..fa56b4589 100644
--- a/docs/quick_tutorial/functional_testing.rst
+++ b/docs/quick_tutorial/functional_testing.rst
@@ -36,15 +36,15 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r unit_testing functional_testing; cd functional_testing
-    $ $VENV/bin/pip install -e .
-    $ $VENV/bin/pip install webtest
+       cd ..; cp -r unit_testing functional_testing; cd functional_testing
+       $VENV/bin/pip install -e .
+       $VENV/bin/pip install webtest
 
 #. Let's extend ``functional_testing/tutorial/tests.py`` to include a
    functional test:
 
    .. literalinclude:: functional_testing/tutorial/tests.py
-    :linenos:
+       :linenos:
 
    Be sure this file is not executable, or ``pytest`` may not include your
    tests.
@@ -53,9 +53,9 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ..
-    2 passed in 0.25 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ..
+       2 passed in 0.25 seconds
 
 
 Analysis
diff --git a/docs/quick_tutorial/hello_world.rst b/docs/quick_tutorial/hello_world.rst
index 94242f1f4..161f07ac8 100644
--- a/docs/quick_tutorial/hello_world.rst
+++ b/docs/quick_tutorial/hello_world.rst
@@ -49,18 +49,18 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ~/projects/quick_tutorial; mkdir hello_world; cd hello_world
+       cd ~/projects/quick_tutorial; mkdir hello_world; cd hello_world
 
 #. Copy the following into ``hello_world/app.py``:
 
    .. literalinclude:: hello_world/app.py
-    :linenos:
+       :linenos:
 
 #. Run the application:
 
    .. code-block:: bash
 
-    $ $VENV/bin/python app.py
+       $VENV/bin/python app.py
 
 #. Open http://localhost:6543/ in your browser.
 
@@ -95,13 +95,13 @@ Extra credit
 
    .. code-block:: python
 
-      print('Incoming request')
+       print('Incoming request')
 
    ...instead of:
 
    .. code-block:: python
 
-      print 'Incoming request'
+       print 'Incoming request'
 
 #. What happens if you return a string of HTML? A sequence of integers?
 
diff --git a/docs/quick_tutorial/ini.rst b/docs/quick_tutorial/ini.rst
index e4f30405f..ce92914fe 100644
--- a/docs/quick_tutorial/ini.rst
+++ b/docs/quick_tutorial/ini.rst
@@ -39,44 +39,44 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r package ini; cd ini
+       cd ..; cp -r package ini; cd ini
 
 #. Our ``ini/setup.py`` needs a setuptools "entry point" in the ``setup()``
    function:
 
    .. literalinclude:: ini/setup.py
-    :linenos:
+       :linenos:
 
 #. We can now install our project, thus generating (or re-generating) an "egg"
    at ``ini/tutorial.egg-info``:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pip install -e .
+       $VENV/bin/pip install -e .
 
 #. Let's make a file ``ini/development.ini`` for our configuration:
 
    .. literalinclude:: ini/development.ini
-    :language: ini
-    :linenos:
+       :language: ini
+       :linenos:
 
 #. We can refactor our startup code from the previous step's ``app.py`` into
    ``ini/tutorial/__init__.py``:
 
    .. literalinclude:: ini/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Now that ``ini/tutorial/app.py`` isn't used, let's remove it:
 
    .. code-block:: bash
 
-    $ rm tutorial/app.py
+       rm tutorial/app.py
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/.
 
diff --git a/docs/quick_tutorial/jinja2.rst b/docs/quick_tutorial/jinja2.rst
index 4faa81fc4..87122a374 100644
--- a/docs/quick_tutorial/jinja2.rst
+++ b/docs/quick_tutorial/jinja2.rst
@@ -27,38 +27,38 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes jinja2; cd jinja2
-    $ $VENV/bin/pip install -e .
-    $ $VENV/bin/pip install pyramid_jinja2
+       cd ..; cp -r view_classes jinja2; cd jinja2
+       $VENV/bin/pip install -e .
+       $VENV/bin/pip install pyramid_jinja2
 
 #. We need to include ``pyramid_jinja2`` in ``jinja2/tutorial/__init__.py``:
 
    .. literalinclude:: jinja2/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Our ``jinja2/tutorial/views.py`` simply changes its ``renderer``:
 
    .. literalinclude:: jinja2/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Add ``jinja2/tutorial/home.jinja2`` as a template:
 
    .. literalinclude:: jinja2/tutorial/home.jinja2
-    :language: html
+       :language: html
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.40 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.40 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in your browser.
 
diff --git a/docs/quick_tutorial/json.rst b/docs/quick_tutorial/json.rst
index ff153d2b5..98283424c 100644
--- a/docs/quick_tutorial/json.rst
+++ b/docs/quick_tutorial/json.rst
@@ -31,32 +31,32 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes json; cd json
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes json; cd json
+       $VENV/bin/pip install -e .
 
 #. We add a new route for ``hello_json`` in ``json/tutorial/__init__.py``:
 
    .. literalinclude:: json/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Rather than implement a new view, we will "stack" another decorator on the
    ``hello`` view in ``views.py``:
 
    .. literalinclude:: json/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. We need a new functional test at the end of ``json/tutorial/tests.py``:
 
    .. literalinclude:: json/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    .....
-    5 passed in 0.47 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       .....
+       5 passed in 0.47 seconds
 
 
 #. Run your Pyramid application with:
diff --git a/docs/quick_tutorial/logging.rst b/docs/quick_tutorial/logging.rst
index 0a530e91f..ccbb7970f 100644
--- a/docs/quick_tutorial/logging.rst
+++ b/docs/quick_tutorial/logging.rst
@@ -36,13 +36,13 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes logging; cd logging
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes logging; cd logging
+       $VENV/bin/pip install -e .
 
 #. Extend ``logging/tutorial/views.py`` to log a message:
 
    .. literalinclude:: logging/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Finally let's edit ``development.ini`` configuration file to enable logging
    for our Pyramid application:
@@ -54,15 +54,15 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.41 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.41 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
    Note, both in the console and in the debug toolbar, the message that you
diff --git a/docs/quick_tutorial/more_view_classes.rst b/docs/quick_tutorial/more_view_classes.rst
index db1c68168..15452e9ae 100644
--- a/docs/quick_tutorial/more_view_classes.rst
+++ b/docs/quick_tutorial/more_view_classes.rst
@@ -57,63 +57,63 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r templating more_view_classes; cd more_view_classes
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r templating more_view_classes; cd more_view_classes
+       $VENV/bin/pip install -e .
 
 #. Our route in ``more_view_classes/tutorial/__init__.py`` needs some
    replacement patterns:
 
    .. literalinclude:: more_view_classes/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Our ``more_view_classes/tutorial/views.py`` now has a view class with
    several views:
 
    .. literalinclude:: more_view_classes/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Our primary view needs a template at ``more_view_classes/tutorial/home.pt``:
 
    .. literalinclude:: more_view_classes/tutorial/home.pt
-    :language: html
+       :language: html
 
 #. Ditto for our other view from the previous section at
    ``more_view_classes/tutorial/hello.pt``:
 
    .. literalinclude:: more_view_classes/tutorial/hello.pt
-    :language: html
+       :language: html
 
 #. We have an edit view that also needs a template at
    ``more_view_classes/tutorial/edit.pt``:
 
    .. literalinclude:: more_view_classes/tutorial/edit.pt
-    :language: html
+       :language: html
 
 #. And finally the delete view's template at
    ``more_view_classes/tutorial/delete.pt``:
 
    .. literalinclude:: more_view_classes/tutorial/delete.pt
-    :language: html
+       :language: html
 
 #. Our tests in ``more_view_classes/tutorial/tests.py`` fail, so let's modify
    them:
 
    .. literalinclude:: more_view_classes/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ..
-    2 passed in 0.40 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ..
+       2 passed in 0.40 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/howdy/jane/doe in your browser. Click the
    ``Save`` and ``Delete`` buttons, and watch the output in the console window.
@@ -161,13 +161,13 @@ previously hardcoded the URLs, such as:
 
 .. code-block:: html
 
-  <a href="/howdy/jane/doe">Howdy</a>
+    <a href="/howdy/jane/doe">Howdy</a>
 
 In ``home.pt`` we switched to:
 
 .. code-block:: xml
 
-  <a href="${request.route_url('hello', first='jane',
+    <a href="${request.route_url('hello', first='jane',
         last='doe')}">form</a>
 
 Pyramid has rich facilities to help generate URLs in a flexible, non-error
diff --git a/docs/quick_tutorial/package.rst b/docs/quick_tutorial/package.rst
index 34bc0f7eb..ae82fef03 100644
--- a/docs/quick_tutorial/package.rst
+++ b/docs/quick_tutorial/package.rst
@@ -53,7 +53,7 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; mkdir package; cd package
+       cd ..; mkdir package; cd package
 
 #. In ``package/setup.py``, enter the following:
 
@@ -64,8 +64,8 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/pip install -e .
-    $ mkdir tutorial
+       $VENV/bin/pip install -e .
+       mkdir tutorial
 
 #. Enter the following into ``package/tutorial/__init__.py``:
 
@@ -79,7 +79,7 @@ Steps
 
    .. code-block:: bash
 
-    $ $VENV/bin/python tutorial/app.py
+       $VENV/bin/python tutorial/app.py
 
 #. Open http://localhost:6543/ in your browser.
 
diff --git a/docs/quick_tutorial/request_response.rst b/docs/quick_tutorial/request_response.rst
index ece8cdd6f..098753820 100644
--- a/docs/quick_tutorial/request_response.rst
+++ b/docs/quick_tutorial/request_response.rst
@@ -39,37 +39,37 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes request_response; cd request_response
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes request_response; cd request_response
+       $VENV/bin/pip install -e .
 
 #. Simplify the routes in ``request_response/tutorial/__init__.py``:
 
    .. literalinclude:: request_response/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. We only need one view in ``request_response/tutorial/views.py``:
 
    .. literalinclude:: request_response/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Update the tests in ``request_response/tutorial/tests.py``:
 
    .. literalinclude:: request_response/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    .....
-    5 passed in 0.30 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       .....
+       5 passed in 0.30 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in your browser. You will be redirected to
    http://localhost:6543/plain.
@@ -91,7 +91,7 @@ the body of the response:
 
 .. code-block:: text
 
-  URL http://localhost:6543/plain?name=alice with name: alice
+    URL http://localhost:6543/plain?name=alice with name: alice
 
 Finally, we set the response's content type and body, then return the response.
 
diff --git a/docs/quick_tutorial/requirements.rst b/docs/quick_tutorial/requirements.rst
index 29f263176..08ea93cb2 100644
--- a/docs/quick_tutorial/requirements.rst
+++ b/docs/quick_tutorial/requirements.rst
@@ -33,7 +33,7 @@ This *Quick Tutorial* is based on:
   projects* (a directory with packaging information and *Python packages* of
   working code.)
 
-* **Unix commands**. Commands in this tutorial use UNIX syntax and paths.
+* **Unix commands**. Commands in this tutorial use Unix syntax and paths.
   Windows users should adjust commands accordingly.
 
 .. note::
@@ -62,7 +62,7 @@ Install Python 3
 See the detailed recommendation for your operating system described under
 :ref:`installing_chapter`.
 
-- :ref:`for-mac-os-x-users`
+- :ref:`for-macos-users`
 - :ref:`if-you-don-t-yet-have-a-python-interpreter-unix`
 - :ref:`if-you-don-t-yet-have-a-python-interpreter-windows`
 
@@ -89,23 +89,23 @@ will reside as we proceed through the tutorial:
                 │   └── app.py
                 └── setup.py
 
-For Linux, the commands to do so are as follows:
+For macOS and Linux, the commands to do so are as follows:
 
 .. code-block:: bash
 
-    # Mac and Linux
-    $ cd ~
-    $ mkdir -p projects/quick_tutorial
-    $ cd projects/quick_tutorial
+    # macOS and Linux
+    cd ~
+    mkdir -p projects/quick_tutorial
+    cd projects/quick_tutorial
 
 For Windows:
 
 .. code-block:: doscon
 
     # Windows
-    c:\> cd \
-    c:\> mkdir projects\quick_tutorial
-    c:\> cd projects\quick_tutorial
+    cd \
+    mkdir projects\quick_tutorial
+    cd projects\quick_tutorial
 
 In the above figure, your user home directory is represented by ``~``. In your
 home directory, all of your projects are in the ``projects`` directory. This is
@@ -129,13 +129,13 @@ environment`. We set an environment variable to save typing later.
 
 .. code-block:: bash
 
-    # Mac and Linux
-    $ export VENV=~/projects/quick_tutorial/env
+    # macOS and Linux
+    export VENV=~/projects/quick_tutorial/env
 
 .. code-block:: doscon
 
     # Windows
-    c:\> set VENV=c:\projects\quick_tutorial\env
+    set VENV=c:\projects\quick_tutorial\env
 
 
 .. _create-a-virtual-environment:
@@ -150,13 +150,13 @@ environment variable.
 
 .. code-block:: bash
 
-    # Mac and Linux
-    $ python3 -m venv $VENV
+    # macOS and Linux
+    python3 -m venv $VENV
 
 .. code-block:: doscon
 
     # Windows
-    c:\> python -m venv %VENV%
+    python -m venv %VENV%
 
 .. seealso:: See also Python 3's :mod:`venv module <python:venv>` and Python
    2's `virtualenv <https://virtualenv.pypa.io/en/latest/>`_ package.
@@ -171,13 +171,13 @@ time of its release.
 
 .. code-block:: bash
 
-    # Mac and Linux
-    $ $VENV/bin/pip install --upgrade pip setuptools
+    # macOS and Linux
+    $VENV/bin/pip install --upgrade pip setuptools
 
 .. code-block:: doscon
 
     # Windows
-    c:\> %VENV%\Scripts\pip install --upgrade pip setuptools
+    %VENV%\Scripts\pip install --upgrade pip setuptools
 
 .. seealso:: See also :ref:`Why use $VENV/bin/pip instead of source
    bin/activate, then pip <venv-bin-pip-vs-source-bin-activate>`.
@@ -193,11 +193,11 @@ part is pretty easy. We'll also install a WSGI server, Waitress.
 
 .. parsed-literal::
 
-    # Mac and Linux
-    $ $VENV/bin/pip install "pyramid==\ |release|\ " waitress
+    # macOS and Linux
+    $VENV/bin/pip install "pyramid==\ |release|\ " waitress
 
     # Windows
-    c:\\> %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " waitress
+    %VENV%\\Scripts\\pip install "pyramid==\ |release|\ " waitress
 
 Our Python virtual environment now has the Pyramid software available
 as well as the ``waitress`` package.
diff --git a/docs/quick_tutorial/routing.rst b/docs/quick_tutorial/routing.rst
index adbe76a62..0384892b2 100644
--- a/docs/quick_tutorial/routing.rst
+++ b/docs/quick_tutorial/routing.rst
@@ -50,44 +50,44 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes routing; cd routing
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes routing; cd routing
+       $VENV/bin/pip install -e .
 
 #. Our ``routing/tutorial/__init__.py`` needs a route with a replacement
    pattern:
 
    .. literalinclude:: routing/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. We just need one view in ``routing/tutorial/views.py``:
 
    .. literalinclude:: routing/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. We just need one view in ``routing/tutorial/home.pt``:
 
    .. literalinclude:: routing/tutorial/home.pt
-    :language: html
-    :linenos:
+       :language: html
+       :linenos:
 
 #. Update ``routing/tutorial/tests.py``:
 
    .. literalinclude:: routing/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ..
-    2 passed in 0.39 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ..
+       2 passed in 0.39 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/howdy/amy/smith in your browser.
 
diff --git a/docs/quick_tutorial/sessions.rst b/docs/quick_tutorial/sessions.rst
index df4887a4b..d67a5063a 100644
--- a/docs/quick_tutorial/sessions.rst
+++ b/docs/quick_tutorial/sessions.rst
@@ -36,39 +36,39 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes sessions; cd sessions
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes sessions; cd sessions
+       $VENV/bin/pip install -e .
 
 #. Our ``sessions/tutorial/__init__.py`` needs a choice of session factory to
    get registered with the :term:`configurator`:
 
    .. literalinclude:: sessions/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Our views in ``sessions/tutorial/views.py`` can now use ``request.session``:
 
    .. literalinclude:: sessions/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. The template at ``sessions/tutorial/home.pt`` can display the value:
 
    .. literalinclude:: sessions/tutorial/home.pt
-    :language: html
-    :linenos:
+       :language: html
+       :linenos:
 
 #. Make sure the tests still pass:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.42 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.42 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
    As you reload and switch between those URLs, note that the counter increases
diff --git a/docs/quick_tutorial/static_assets.rst b/docs/quick_tutorial/static_assets.rst
index 81a01061a..7a6b5dac3 100644
--- a/docs/quick_tutorial/static_assets.rst
+++ b/docs/quick_tutorial/static_assets.rst
@@ -23,46 +23,46 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r view_classes static_assets; cd static_assets
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r view_classes static_assets; cd static_assets
+       $VENV/bin/pip install -e .
 
 #. We add a call ``config.add_static_view`` in
    ``static_assets/tutorial/__init__.py``:
 
    .. literalinclude:: static_assets/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. We can add a CSS link in the ``<head>`` of our template at
    ``static_assets/tutorial/home.pt``:
 
    .. literalinclude:: static_assets/tutorial/home.pt
-    :language: html
+       :language: html
 
 #. Add a CSS file at ``static_assets/tutorial/static/app.css``:
 
    .. literalinclude:: static_assets/tutorial/static/app.css
-    :language: css
+       :language: css
 
 #. We add a functional test that asserts that the newly added static file is delivered:
 
    .. literalinclude:: static_assets/tutorial/tests.py
-    :language: python
-    :pyobject: TutorialFunctionalTests.test_css
-    :lineno-match:
+       :language: python
+       :pyobject: TutorialFunctionalTests.test_css
+       :lineno-match:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    5 passed in 0.50 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       5 passed in 0.50 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ in your browser and note the new font.
 
@@ -82,7 +82,7 @@ disk? Pyramid gives a helper that provides flexibility on URL generation:
 
 .. code-block:: html
 
-  ${request.static_url('tutorial:static/app.css')}
+    ${request.static_url('tutorial:static/app.css')}
 
 This matches the ``path='tutorial:static'`` in our ``config.add_static_view``
 registration. By using ``request.static_url`` to generate the full URL to the
diff --git a/docs/quick_tutorial/templating.rst b/docs/quick_tutorial/templating.rst
index ec6de98f8..3fbef699c 100644
--- a/docs/quick_tutorial/templating.rst
+++ b/docs/quick_tutorial/templating.rst
@@ -47,60 +47,60 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r views templating; cd templating
+       cd ..; cp -r views templating; cd templating
 
 #. This step depends on ``pyramid_chameleon``, so add it as a dependency in
    ``templating/setup.py``:
 
    .. literalinclude:: templating/setup.py
-    :linenos:
+       :linenos:
 
 #. Now we can activate the development-mode distribution:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pip install -e .
+       $VENV/bin/pip install -e .
 
 #. We need to connect ``pyramid_chameleon`` as a renderer by making a call in
    the setup of ``templating/tutorial/__init__.py``:
 
    .. literalinclude:: templating/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Our ``templating/tutorial/views.py`` no longer has HTML in it:
 
    .. literalinclude:: templating/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Instead we have ``templating/tutorial/home.pt`` as a template:
 
    .. literalinclude:: templating/tutorial/home.pt
-    :language: html
+       :language: html
 
 #. For convenience, change ``templating/development.ini`` to reload templates
    automatically with ``pyramid.reload_templates``:
 
    .. literalinclude:: templating/development.ini
-    :language: ini
+       :language: ini
 
 #. Our unit tests in ``templating/tutorial/tests.py`` can focus on data:
 
    .. literalinclude:: templating/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.46 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.46 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
 
diff --git a/docs/quick_tutorial/tutorial_approach.rst b/docs/quick_tutorial/tutorial_approach.rst
index 83b229746..7ef28bdb8 100644
--- a/docs/quick_tutorial/tutorial_approach.rst
+++ b/docs/quick_tutorial/tutorial_approach.rst
@@ -40,7 +40,7 @@ For most steps you will copy the previous step's directory to a new directory, a
 
 .. code-block:: bash
 
-    $ cd ..; cp -r package ini; cd ini
-    $ $VENV/bin/pip install -e .
+    cd ..; cp -r package ini; cd ini
+    $VENV/bin/pip install -e .
 
 For a few steps, you won't copy the previous step's directory, but you will still need to install your project with ``$VENV/bin/pip install -e .``.
diff --git a/docs/quick_tutorial/unit_testing.rst b/docs/quick_tutorial/unit_testing.rst
index 63fe7c945..09e3ea197 100644
--- a/docs/quick_tutorial/unit_testing.rst
+++ b/docs/quick_tutorial/unit_testing.rst
@@ -48,23 +48,23 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
-    $ $VENV/bin/pip install -e .
-    $ $VENV/bin/pip install pytest
+       cd ..; cp -r debugtoolbar unit_testing; cd unit_testing
+       $VENV/bin/pip install -e .
+       $VENV/bin/pip install pytest
 
 #. Now we write a simple unit test in ``unit_testing/tutorial/tests.py``:
 
    .. literalinclude:: unit_testing/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    .
-    1 passed in 0.14 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       .
+       1 passed in 0.14 seconds
 
 
 Analysis
diff --git a/docs/quick_tutorial/view_classes.rst b/docs/quick_tutorial/view_classes.rst
index 49cdcddcc..fc7ba5125 100644
--- a/docs/quick_tutorial/view_classes.rst
+++ b/docs/quick_tutorial/view_classes.rst
@@ -41,36 +41,35 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r templating view_classes; cd view_classes
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r templating view_classes; cd view_classes
+       $VENV/bin/pip install -e .
 
 #. Our ``view_classes/tutorial/views.py`` now has a view class with our two
    views:
 
    .. literalinclude:: view_classes/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Our unit tests in ``view_classes/tutorial/tests.py`` don't run, so let's
    modify them to import the view class, and make an instance before getting a
    response:
 
    .. literalinclude:: view_classes/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
-
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.34 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.34 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ and http://localhost:6543/howdy in your browser.
 
diff --git a/docs/quick_tutorial/views.rst b/docs/quick_tutorial/views.rst
index edbe4b2ff..f7fa64719 100644
--- a/docs/quick_tutorial/views.rst
+++ b/docs/quick_tutorial/views.rst
@@ -44,39 +44,39 @@ Steps
 
    .. code-block:: bash
 
-    $ cd ..; cp -r functional_testing views; cd views
-    $ $VENV/bin/pip install -e .
+       cd ..; cp -r functional_testing views; cd views
+       $VENV/bin/pip install -e .
 
 #. Our ``views/tutorial/__init__.py`` gets a lot shorter:
 
    .. literalinclude:: views/tutorial/__init__.py
-    :linenos:
+       :linenos:
 
 #. Let's add a module ``views/tutorial/views.py`` that is focused on
    handling requests and responses:
 
    .. literalinclude:: views/tutorial/views.py
-    :linenos:
+       :linenos:
 
 #. Update the tests to cover the two new views:
 
    .. literalinclude:: views/tutorial/tests.py
-    :linenos:
+       :linenos:
 
 #. Now run the tests:
 
    .. code-block:: bash
 
 
-    $ $VENV/bin/py.test tutorial/tests.py -q
-    ....
-    4 passed in 0.28 seconds
+       $VENV/bin/py.test tutorial/tests.py -q
+       ....
+       4 passed in 0.28 seconds
 
 #. Run your Pyramid application with:
 
    .. code-block:: bash
 
-    $ $VENV/bin/pserve development.ini --reload
+       $VENV/bin/pserve development.ini --reload
 
 #. Open http://localhost:6543/ and http://localhost:6543/howdy
    in your browser.