From 8c4210f94132e2ba844732bd1dada82696fc20db Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jun 2012 11:03:56 -0400 Subject: how to build HTML docs --- HACKING.txt | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 593e89ac1..ec0bcb000 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -48,6 +48,23 @@ checkout. $ 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``. + Adding Features --------------- -- cgit v1.2.3 From c7fcdf1665cfdc1173559baa0a56d9a06fcba448 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 11 Jun 2012 11:16:07 -0400 Subject: consolidate --- HACKING.txt | 46 +++++++++++++++++----------------------------- 1 file changed, 17 insertions(+), 29 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index ec0bcb000..dd735bf22 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -48,23 +48,6 @@ checkout. $ 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``. - Adding Features --------------- @@ -130,23 +113,28 @@ Test Coverage ``nose`` and ``coverage`` into your virtualenv, 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 ``$yourvenv/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. cd to the ``docs`` directory within your 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. - 3. Open the _build/html/index.html file to see the resulting rendering. +3. Open the ``docs/_build/html/index.html`` file to see the resulting HTML + rendering. Change Log ---------- -- cgit v1.2.3 From 6ef753257617acf8aaf3daaca22de3783970cffe Mon Sep 17 00:00:00 2001 From: Jeff Cook Date: Wed, 4 Jul 2012 18:52:54 -0600 Subject: Include instructions for recursive submodule checkout of Sphinx themes. --- HACKING.txt | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index dd735bf22..38c263ed7 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -127,13 +127,19 @@ using to develop Pyramid): 1. Run ``$yourvenv/bin/python setup.py dev docs``. This will cause Sphinx and all development requirements to be installed in your virtualenv. -2. cd to the ``docs`` directory within your Pyramid checkout and execute +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. cd to the ``docs`` directory within your 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. -3. Open the ``docs/_build/html/index.html`` file to see the resulting HTML +4. Open the ``docs/_build/html/index.html`` file to see the resulting HTML rendering. Change Log -- cgit v1.2.3 From cdcea948c3f6f3abbd1772500029066e80825082 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 15 Aug 2012 12:57:29 -0400 Subject: note whitespace rules, explain setup.py dev --- HACKING.txt | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) (limited to 'HACKING.txt') diff --git a/HACKING.txt b/HACKING.txt index 38c263ed7..87d1422dc 100644 --- a/HACKING.txt +++ b/HACKING.txt @@ -30,11 +30,13 @@ checkout. $ env/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 + $ ../env/bin/python setup.py dev - At that point, you should be able to create new Pyramid projects by using ``pcreate``:: @@ -85,6 +87,9 @@ Coding Style 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. + Running Tests -------------- @@ -110,8 +115,8 @@ Test Coverage - 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 and Building HTML Documentation ------------------------------------------------------ -- cgit v1.2.3