…and wiki tutorial

docs/Makefile

@@ -12,16 +12,20 @@ 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 web pickle htmlhelp latex changes linkcheck
.PHONY: help clean html text web pickle htmlhelp latex latexpdf changes linkcheck epub doctest

help:
	@echo "Please use \`make <target>' where <target> is one of"
	@echo "  html      to make standalone HTML 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 "  changes   to make an overview over all changed/added/deprecated items"
	@echo "  linkcheck to check all external links for integrity"
	@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 "  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)/*
@@ -90,3 +94,7 @@ 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."

docs/conf.py

@@ -65,8 +65,8 @@ def nothing(*arg):
    'deform': ('http://docs.pylonsproject.org/projects/deform/en/latest', None),
    'jinja2': ('http://docs.pylonsproject.org/projects/pyramid-jinja2/en/latest/', None),
    'pylonswebframework': ('http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None),
    'python': ('http://docs.python.org', None),
    'python3': ('http://docs.python.org/3', None),
    'python': ('https://docs.python.org/2/', None),
    'python3': ('http://docs.python.org/3/', None),
    'sqla': ('http://docs.sqlalchemy.org/en/latest', None),
    'tm': ('http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None),
    'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None),
@@ -125,6 +125,7 @@ def nothing(*arg):

# Options for HTML output
# -----------------------
# enable pylons_sphinx_latesturl when this branch is no longer "latest"
pylons_sphinx_latesturl_base = (
    'http://docs.pylonsproject.org/projects/pyramid/en/latest/')
pylons_sphinx_latesturl_pagename_overrides = {
@@ -144,9 +145,10 @@ def nothing(*arg):
html_theme_path = pylons_sphinx_themes.get_html_themes_path()
html_theme_options = dict(
    github_url='https://github.com/Pylons/pyramid',
    # on master branch true, else false
    # On master branch and new branch still in
    # pre-release status: true; else: false.
    in_progress='false',
    # on previous branches/major releases true, else false
    # On branches previous to "latest": true; else: false.
    outdated='true',
    )

docs/conventions.rst

@@ -35,7 +35,7 @@ References to glossary terms are presented using the following style:

URLs are presented using the following style:

  `Pylons <http://pylonsproject.org>`_
  `Pylons <http://www.pylonsproject.org>`_

References to sections and chapters are presented using the following
style:
@@ -53,46 +53,39 @@ Code and configuration file blocks are presented in the following style:
Example blocks representing UNIX shell commands are prefixed with a ``$``
character, e.g.:

  .. code-block:: text
  .. code-block:: bash

     $ $VENV/bin/nosetests

(See :term:`virtualenv` for the meaning of ``$VENV``)
See :term:`virtualenv` for the meaning of ``$VENV``.

Example blocks representing Windows ``cmd.exe`` commands are prefixed with a
drive letter and/or a directory name, e.g.:
Example blocks representing Windows commands are prefixed with a drive letter
with an optional directory name, e.g.:

  .. code-block:: text
  .. code-block:: doscon

     c:\examples> %VENV%\Scripts\nosetests

(See :term:`virtualenv` for the meaning of ``%VENV%``)

Sometimes, when it's unknown which directory is current, Windows ``cmd.exe``
example block commands are prefixed only with a ``>`` character, e.g.:

  .. code-block:: text

     > %VENV%\Scripts\nosetests
See :term:`venv` for the meaning of ``%VENV%``.

When a command that should be typed on one line is too long to fit on a page,
the backslash ``\`` is used to indicate that the following printed line
should actually be part of the command:
the backslash ``\`` is used to indicate that the following printed line should
be part of the command:

  .. code-block:: text
  .. code-block:: bash

     c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \
           --cover-erase --with-coverage
     $ $VENV/bin/nosetests --cover-package=tutorial --cover-erase \
          --with-coverage

A sidebar, which presents a concept tangentially related to content
discussed on a page, is rendered like so:
A sidebar, which presents a concept tangentially related to content discussed
on a page, is rendered like so:

.. sidebar:: This is a sidebar

   Sidebar information.

When multiple objects are imported from the same package,
the following convention is used:
When multiple objects are imported from the same package, the following
convention is used:

    .. code-block:: python

@@ -103,9 +96,9 @@ the following convention is used:

It may look unusual, but it has advantages:

* It allows one to swap out the higher-level package ``foo`` for something
  else that provides the similar API. An example would be swapping out
  one database for another (e.g., graduating from SQLite to PostgreSQL).
* It allows one to swap out the higher-level package ``foo`` for something else
  that provides the similar API. An example would be swapping out one database
  for another (e.g., graduating from SQLite to PostgreSQL).

* Looks more neat in cases where a large number of objects get imported from
  that package.

docs/copyright.rst

@@ -1,7 +1,7 @@
Copyright, Trademarks, and Attributions
=======================================

*The Pyramid Web Framework, Version 1.1*
"The Pyramid Web Framework, Version |version|"

by Chris McDonough

@@ -63,7 +63,7 @@ Contributors:
  GitHub.

Cover Designer:
   Hugues Laflamme of `Kemeneur <http://www.kemeneur.com/>`_.
   Hugues Laflamme of Kemeneur.

Used with permission:

@@ -80,8 +80,8 @@ Print Production
----------------

The print version of this book was produced using the `Sphinx
<http://sphinx.pocoo.org/>`_ documentation generation system and the
`LaTeX <http://www.latex-project.org/>`_ typesetting system.
<http://www.sphinx-doc.org/en/stable/>`_ documentation generation system and
the `LaTeX <http://www.latex-project.org/>`_ typesetting system.

Contacting The Publisher
------------------------
@@ -90,7 +90,7 @@ Please send documentation licensing inquiries, translation inquiries,
and other business communications to `Agendaless Consulting
<mailto:webmaster@agendaless.com>`_.  Please send software and other
technical queries to the `Pylons-devel mailing list
<http://groups.google.com/group/pylons-devel>`_.
<https://groups.google.com/forum/#!forum/pylons-devel>`_.

HTML Version and Source Code
----------------------------
@@ -101,4 +101,3 @@ http://docs.pylonsproject.org/projects/pyramid/en/latest/
The source code for the examples used in this book are available
within the :app:`Pyramid` software distribution, always available
via https://github.com/Pylons/pyramid

docs/designdefense.rst

@@ -1009,7 +1009,7 @@ Microframeworks have smaller Hello World programs
Self-described "microframeworks" exist. `Bottle
<http://bottlepy.org/docs/dev/index.html>`_ and `Flask
<http://flask.pocoo.org/>`_ are two that are becoming popular. `Bobo
<http://bobo.digicool.com/en/latest/>`_ doesn't describe itself as a
<https://bobo.readthedocs.io/en/latest/>`_ doesn't describe itself as a
microframework, but its intended user base is much the same. Many others exist.
We've even (only as a teaching tool, not as any sort of official project)
`created one using Pyramid <http://static.repoze.org/casts/videotags.html>`_.