Merge branch 'master' of github.com:Pylons/pyramid

Chris McDonough

2013-06-20 56511b0defbc4437a1e1d3b013c504886270d01b

 HACKING.txt

@@ -27,43 +27,28 @@
- Install ``setuptools-git`` into the virtualenv (for good measure, as we're
  using git to do version control)::

  $ env/bin/easy_install setuptools-git
  $ $VENV/bin/easy_install setuptools-git

- Install Pyramid from the checkout into the virtualenv using ``setup.py
  develop`` (running ``setup.py develop`` *must* be done while the current
  working directory is the ``pyramid`` checkout directory)::
  dev``.  ``setup.py dev`` is an alias for "setup.py develop" which also
  installs testing requirements such as nose and coverage.  Running
  ``setup.py dev`` *must* be done while the current working directory is the
  ``pyramid`` checkout directory::

  $ cd pyramid
  $ ../env/bin/python setup.py develop
  $ $VENV/bin/python setup.py dev

- At that point, you should be able to create new Pyramid projects by using
  ``pcreate``::

  $ cd ../env
  $ bin/pcreate -s starter starter
  $ $VENV/bin/pcreate -s starter starter

- And install those projects (also using ``setup.py develop``) into the
  virtualenv::

  $ cd starter
  $ ../bin/python setup.py develop

Building the HTML Docs
-----------------------

- Check out Pyramid from Github.

- Create a virtualenv or reuse an existing one that you're using to develop
  Pyramid.

- Run  ``$yourvenv/bin/python setup.py dev docs``.

- cd to ``docs`` within the Pyramid checkout and execute ``make clean html
  SPHINXBUILD=$yourvenv/bin/sphinx-build``.  The ``SPHINXBUILD=...`` hair is
  there in order to tell it to use the virtualenv Python, which will have
  both Sphinx and Pyramid (for API documentation generation) installed.

- The rendered HTML docs will end up in ``docs/_build/html``.
  $ $VENV/bin/python setup.py develop

Adding Features
---------------
@@ -102,11 +87,14 @@
  2 newlines between classes.  But 80-column lines, in particular, are
  mandatory.

- Please do not remove trailing whitespace.  Configure your editor to reduce
  diff noise. See https://github.com/Pylons/pyramid/issues/788 for more.

Running Tests
--------------

- To run tests for Pyramid on a single Python version, run ``python setup.py
  test`` against the using the Python interpreter from virtualenv into which
  test`` against the Python interpreter from virtualenv into which
  you've ``setup.py develop``-ed Pyramid.

- To run the full set of Pyramid tests on all platforms, install ``tox``
@@ -127,26 +115,37 @@

- The codebase *must* have 100% test statement coverage after each commit.
  You can test coverage via ``tox -e coverage``, or alternately by installing
  ``nose`` and ``coverage`` into your virtualenv, and running ``setup.py
  nosetests --with-coverage``.
  ``nose`` and ``coverage`` into your virtualenv (easiest via ``setup.py
  dev``) , and running ``setup.py nosetests --with-coverage``.

Documentation Coverage
----------------------
Documentation Coverage and Building HTML Documentation
------------------------------------------------------

- If you fix a bug, and the bug requires an API or behavior
  modification, all documentation in this package which references
  that API or behavior must change to reflect the bug fix, ideally in
  the same commit that fixes the bug or adds the feature.
If you fix a bug, and the bug requires an API or behavior modification, all
documentation in this package which references that API or behavior must
change to reflect the bug fix, ideally in the same commit that fixes the bug
or adds the feature.

- To build and review docs:
To build and review docs (where ``$yourvenv`` refers to the virtualenv you're
using to develop Pyramid):

  1. Install ``tests_require`` dependencies from Pyramid's setup.py into your
     virtualenv.
1. Run ``$VENV/bin/python setup.py dev docs``.  This will cause Sphinx
   and all development requirements to be installed in your virtualenv.

  2. From the ``docs`` directory of the Pyramid checkout run ``make html
     SPHINXBUILD=/path/to/your/virtualenv/bin/sphinx-build``.
2. Update all git submodules from the top-level of your Pyramid checkout, like
   so:
     git submodule update --init --recursive
   This will checkout theme subrepositories and prevent error conditions when
   HTML docs are generated.

  3.  Open the _build/html/index.html file to see the resulting rendering.
3. cd to the ``docs`` directory within your Pyramid checkout and execute
   ``make clean html SPHINXBUILD=$VENV/bin/sphinx-build``.  The
   ``SPHINXBUILD=...`` hair is there in order to tell it to use the
   virtualenv Python, which will have both Sphinx and Pyramid (for API
   documentation generation) installed.

4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML
   rendering.

Change Log
----------