Getting up-to-date before pushing changes

docs/Makefile

@@ -7,12 +7,19 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
@@ -27,14 +34,20 @@ help:
 	@echo "  epub       to make an epub"
 	@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 "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
 	@echo "  text       to make text files"
 	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
 	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
 	@echo "  linkcheck  to check all external links for integrity"
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	rm -rf $(BUILDDIR)/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@@ -72,17 +85,17 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/osxpython.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pythonguide.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/osxpython.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pythonguide.qhc"
 
 devhelp:
 	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/osxpython"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/pythonguide"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/osxpython"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pythonguide"
 	@echo "# devhelp"
 
 epub:
@@ -100,7 +113,13 @@ latex:
 latexpdf:
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
 	@echo "Running LaTeX files through pdflatex..."
-	make -C $(BUILDDIR)/latex all-pdf
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
 	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
 
 text:
@@ -113,6 +132,24 @@ man:
 	@echo
 	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
 
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
 changes:
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
 	@echo
@@ -128,3 +165,13 @@ doctest:
 	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in $(BUILDDIR)/doctest/output.txt."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

docs/_templates/sidebarintro.html

@@ -31,4 +31,5 @@
   <li><a href="http://python-guide.org/">The Guide Website</a></li>
   <li><a href="http://github.com/kennethreitz/python-guide">The Guide @ GitHub</a></li>
   <li><a href="http://github.com/kennethreitz/python-guide/issues">Issue Tracker</a></li>
+  <li><a href="https://media.readthedocs.org/pdf/python-guide/latest/python-guide.pdf">The Guide as a PDF</a></li>
 </ul>

docs/dev/env.rst

@@ -17,7 +17,7 @@ or icons. There exist a couple of plugins and settings for the VIM editor to
 aid Python development. If you only develop in Python, a good start is to set
 the default settings for indentation and line-wrapping to values compliant with
 :pep:`8`. In your home directory, open a file called `.vimrc` and add the
-following lines:::
+following lines::
 
     set textwidth=79  " lines longer than 79 columns will be broken
     set shiftwidth=4  " operation >> indents 4 columns; << unindents 4 columns
@@ -64,7 +64,7 @@ to do that which also shows status and warning messages in the statusbar would b
 Python-mode
 ^^^^^^^^^^^
 
-Python-mode_ is a complex solution in VIM for working with python code.
+Python-mode_ is a complex solution in VIM for working with Python code.
 It has:
 
 - Asynchronous Python code checking (pylint, pyflakes, pep8, mccabe) in any combination
@@ -94,7 +94,7 @@ Emacs is a powerful text editor. It's fully programmable (lisp), but
 it can be some work to wire up correctly. A good start if you're
 already an Emacs user is `Python Programming in Emacs`_ at EmacsWiki.
 
-1. Emacs itself comes with a python mode.
+1. Emacs itself comes with a Python mode.
 2. Python ships with an alternate version:
    `python-mode.el <https://launchpad.net/python-mode>`_
 3. Fabián Ezequiel Gallina's `python.el <https://github.com/fgallina/python.el>`_
@@ -118,7 +118,7 @@ Sublime Text
     extraordinary features and amazing performance.
 
 Sublime Text has excellent support for editing Python code and uses Python for
-its plugin API. It also has plugins a diverse variety of plugins, `some of which <https://github.com/SublimeLinter/SublimeLinter>`_
+its plugin API. It also has a diverse variety of plugins, `some of which <https://github.com/SublimeLinter/SublimeLinter>`_
 allow for in-editor PEP8 checking and code "linting".
 
 
@@ -130,7 +130,7 @@ PyCharm / IntelliJ IDEA
 
 `PyCharm <http://www.jetbrains.com/pycharm/>`_ is developed by JetBrains, also
 known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
-features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631/>`_.
+features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631>`_.
 
 
 Eclipse

docs/dev/virtualenvs.rst

@@ -140,7 +140,7 @@ Other useful commands
 
 autoenv
 -------
-When you ``cd`` into a directory containing a ``.env`` `autoenv <https://github.com/kennethreitz/autoenv>`_
+When you ``cd`` into a directory containing a ``.env``, `autoenv <https://github.com/kennethreitz/autoenv>`_
 automagically activates the environment.
 
 Install it on Mac OS X using ``brew``:

docs/index.rst

@@ -1,4 +1,4 @@
-.. osxpython documentation master file, created by
+.. pythonguide documentation master file, created by
    sphinx-quickstart on Wed Aug  4 22:51:11 2010.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.

docs/intro/community.rst

@@ -75,7 +75,7 @@ The major events for the Python community are developer conferences. The two
 most notable conferences are PyCon, which is held in the US, and its European
 sibling, EuroPython.
 
-A comprehensive list of conferences is maintained `at pycon.org <http://www.pycon.org/>`_.
+A comprehensive list of conferences is maintained at `pycon.org <http://www.pycon.org/>`_.
 
 
 Python User Groups

docs/intro/learning.rst

@@ -7,9 +7,9 @@ Beginner
 Learn Python Interactive Tutorial
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Learnpython.org is an easy non-intimidating way to get introduced to python.
+Learnpython.org is an easy non-intimidating way to get introduced to Python.
 The website takes the same approach used on the popular `Try Ruby <http://tryruby.org/>`_
-website, it has an interactive python interpreter built into the site that
+website, it has an interactive Python interpreter built into the site that
 allows you to go through the lessons without having to install Python locally.
 
     `Learn Python <http://www.learnpython.org/>`_
@@ -52,11 +52,11 @@ Think Python: How to Think Like a Computer Scientist
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Think Python attempts to give an introduction to basic concepts in computer
-science through the use of the python language. The focus was to create a book
+science through the use of the Python language. The focus was to create a book
 with plenty of exercises, minimal jargon and a section in each chapter devoted
 to the subject of debugging.
 
-While exploring the various features available in the python language the
+While exploring the various features available in the Python language the
 author weaves in various design patterns and best practices.
 
 The book also includes several case studies which have the reader explore the
@@ -72,11 +72,11 @@ Python Koans
 
 Python Koans is a port of Edgecase's Ruby Koans.  It uses a test-driven
 approach, q.v. TEST DRIVEN DESIGN SECTION to provide an interactive tutorial
-teaching basic python concepts.  By fixing assertion statements that fail in a
+teaching basic Python concepts.  By fixing assertion statements that fail in a
-test script, this provides sequential steps to learning python.
+test script, this provides sequential steps to learning Python.
 
 For those used to languages and figuring out puzzles on their own, this can be
-a fun, attractive option. For those new to python and programming, having an
+a fun, attractive option. For those new to Python and programming, having an
 additional resource or reference will be helpful.
 
     `Python Koans <http://bitbucket.org/gregmalcolm/python_koans>`_
@@ -88,7 +88,7 @@ More information about test driven development can be found at these resources:
 A Byte of Python
 ~~~~~~~~~~~~~~~~
 
-A free introductory book that teaches python at the beginner level, it assumes no
+A free introductory book that teaches Python at the beginner level, it assumes no
 previous programming experience.
 
     `A Byte of Python for Python 2.x <http://www.ibiblio.org/swaroopch/byteofpython/read/>`_
@@ -104,6 +104,8 @@ Pro Python
 This book is for intermediate to advanced Python programmers who are looking to understand how
 and why Python works the way it does and how they can take their code to the next level.
 
+    `Pro Python <http://propython.com>`_
+
 
 Expert Python Programming
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -137,16 +139,16 @@ A Primer on Scientific Programming with Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A Primer on Scientific Programming with Python, written by Hans Petter Langtangen,
-mainly covers python's usage in scientific field. In the book, examples are
+mainly covers Python's usage in scientific field. In the book, examples are
-choosen from mathematics and the natural sciences.
+chosen from mathematics and the natural sciences.
 
-    `A Primer on Scientific Programming with Python <http://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-18365-2>`_
+    `A Primer on Scientific Programming with Python <http://www.springer.com/mathematics/computational+science+%26+engineering/book/978-3-642-30292-3>`_
 
 Numerical Methods in Engineering with Python
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Numerical Methods in Engineering with Python,written by Jaan Kiusalaas, attempts to
+Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, attempts to
-emphasis on numerical methods and how to implement them in python.
+emphasis on numerical methods and how to implement them in Python.
 
     `Numerical Methods in Engineering with Python <http://www.cambridge.org/us/academic/subjects/engineering/engineering-mathematics-and-programming/numerical-methods-engineering-python-2nd-edition>`_
 
@@ -157,7 +159,7 @@ Python in a Nutshell
 ~~~~~~~~~~~~~~~~~~~~
 
 Python in a Nutshell, written by Alex Martelli, covers most cross-platform
-python's usage, from its syntax to built-in libraries to advanced topics such
+Python's usage, from its syntax to built-in libraries to advanced topics such
 as writing C extensions.
 
     `Python in a Nutshell <http://shop.oreilly.com/product/9780596001889.do>`_
@@ -169,3 +171,12 @@ This is Python's reference manual, it covers the syntax and the core semantics o
 language.
 
     `The Python Language Reference <http://docs.python.org/reference/index.html>`_
+    
+Python Pocket Reference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python Pocket Reference, written by Mark Lutz, is an easy to use reference to the
+core language, with descriptions of commonly used modules and toolkits. It covers
+Python 3 and 2.6 versions.
+
+    `Python Pocket Reference <http://shop.oreilly.com/product/9780596158095.do>`_

docs/intro/news.rst

@@ -19,7 +19,7 @@ Python-related news.
 Pycoder's Weekly
 ~~~~~~~~~~~~~~~~
 
-Pycoder's Weekly is a free weekly python newsletter for Python developers 
+Pycoder's Weekly is a free weekly Python newsletter for Python developers 
 by Python developers (Project, Articles, News, and Jobs).
 
     `Pycoder's Weekly <http://www.pycoders.com/>`_

docs/make.bat

@@ -7,8 +7,10 @@ if "%SPHINXBUILD%" == "" (
 )
 set BUILDDIR=_build
 set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+set I18NSPHINXOPTS=%SPHINXOPTS% .
 if NOT "%PAPER%" == "" (
 	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+	set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
 )
 
 if "%1" == "" goto help
@@ -28,7 +30,11 @@ if "%1" == "help" (
 	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
 	echo.  text       to make text files
 	echo.  man        to make manual pages
+	echo.  texinfo    to make Texinfo files
+	echo.  gettext    to make PO message catalogs
 	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  xml        to make Docutils-native XML files
+	echo.  pseudoxml  to make pseudoxml-XML files for display purposes
 	echo.  linkcheck  to check all external links for integrity
 	echo.  doctest    to run all doctests embedded in the documentation if enabled
 	goto end
@@ -40,8 +46,34 @@ if "%1" == "clean" (
 	goto end
 )
 
+
+REM Check if sphinx-build is available and fallback to Python version if any
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 goto sphinx_python
+goto sphinx_ok
+
+:sphinx_python
+
+set SPHINXBUILD=python -m sphinx.__init__
+%SPHINXBUILD% 2> nul
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+:sphinx_ok
+
+
 if "%1" == "html" (
 	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
 	goto end
@@ -49,6 +81,7 @@ if "%1" == "html" (
 
 if "%1" == "dirhtml" (
 	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
 	goto end
@@ -56,6 +89,7 @@ if "%1" == "dirhtml" (
 
 if "%1" == "singlehtml" (
 	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
 	goto end
@@ -63,6 +97,7 @@ if "%1" == "singlehtml" (
 
 if "%1" == "pickle" (
 	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the pickle files.
 	goto end
@@ -70,6 +105,7 @@ if "%1" == "pickle" (
 
 if "%1" == "json" (
 	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can process the JSON files.
 	goto end
@@ -77,6 +113,7 @@ if "%1" == "json" (
 
 if "%1" == "htmlhelp" (
 	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run HTML Help Workshop with the ^
 .hhp project file in %BUILDDIR%/htmlhelp.
@@ -85,17 +122,19 @@ if "%1" == "htmlhelp" (
 
 if "%1" == "qthelp" (
 	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; now you can run "qcollectiongenerator" with the ^
 .qhcp project file in %BUILDDIR%/qthelp, like this:
-	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\osxpython.qhcp
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\pythonguide.qhcp
 	echo.To view the help file:
-	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\osxpython.ghc
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\pythonguide.ghc
 	goto end
 )
 
 if "%1" == "devhelp" (
 	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished.
 	goto end
@@ -103,6 +142,7 @@ if "%1" == "devhelp" (
 
 if "%1" == "epub" (
 	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The epub file is in %BUILDDIR%/epub.
 	goto end
@@ -110,13 +150,35 @@ if "%1" == "epub" (
 
 if "%1" == "latex" (
 	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
 	goto end
 )
 
+if "%1" == "latexpdf" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "latexpdfja" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	cd %BUILDDIR%/latex
+	make all-pdf-ja
+	cd %BUILDDIR%/..
+	echo.
+	echo.Build finished; the PDF files are in %BUILDDIR%/latex.
+	goto end
+)
+
 if "%1" == "text" (
 	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The text files are in %BUILDDIR%/text.
 	goto end
@@ -124,13 +186,31 @@ if "%1" == "text" (
 
 if "%1" == "man" (
 	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Build finished. The manual pages are in %BUILDDIR%/man.
 	goto end
 )
 
+if "%1" == "texinfo" (
+	%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
+	goto end
+)
+
+if "%1" == "gettext" (
+	%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
+	goto end
+)
+
 if "%1" == "changes" (
 	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.The overview file is in %BUILDDIR%/changes.
 	goto end
@@ -138,6 +218,7 @@ if "%1" == "changes" (
 
 if "%1" == "linkcheck" (
 	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Link check complete; look for any errors in the above output ^
 or in %BUILDDIR%/linkcheck/output.txt.
@@ -146,10 +227,27 @@ or in %BUILDDIR%/linkcheck/output.txt.
 
 if "%1" == "doctest" (
 	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
 	echo.
 	echo.Testing of doctests in the sources finished, look at the ^
 results in %BUILDDIR%/doctest/output.txt.
 	goto end
 )
 
+if "%1" == "xml" (
+	%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The XML files are in %BUILDDIR%/xml.
+	goto end
+)
+
+if "%1" == "pseudoxml" (
+	%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
+	goto end
+)
+
 :end

docs/scenarios/admin.rst

@@ -6,7 +6,7 @@ Fabric
 
 `Fabric <http://docs.fabfile.org>`_ is a library for simplifying system
 administration tasks. While Chef and Puppet tend to focus on managing servers
-and system libraries, fabric is more focused on application level tasks such
+and system libraries, Fabric is more focused on application level tasks such
 as deployment.
 
 Install Fabric:
@@ -77,7 +77,7 @@ It supports remote command execution from a central point (master host) to multi
 hosts (minions). It also supports system states which can be used to configure
 multiple servers using simple template files.
 
-Salt supports python versions 2.6 and 2.7 and can be installed via pip:
+Salt supports Python versions 2.6 and 2.7 and can be installed via pip:
 
 .. code-block:: console
 
@@ -95,7 +95,7 @@ The following command lists all available minion hosts, using the ping module.
 The host filtering is accomplished by matching the minion id, or using the grains system.
 The `grains <http://docs.saltstack.org/en/latest/topics/targeting/grains.html>`_ system
 uses static host information like the operating system version or the CPU architecture to
-provide a host taxonomy for the salt modules.
+provide a host taxonomy for the Salt modules.
 
 The following command lists all available minions running CentOS using the grains system:
 
@@ -119,7 +119,7 @@ and start the Apache server:
         - require:
           - pkg: apache
 
-State files can be written using YAML, the Jinja2 template system or pure python.
+State files can be written using YAML, the Jinja2 template system or pure Python.
 
     `Salt Documentation <http://docs.saltstack.com>`_
 
@@ -176,6 +176,14 @@ Here is an example to be aware of some server overload. In case of some failed t
 A full terminal application like a widely extended top which is based on psutil and with the ability of a client-server
 monitoring is `glance <https://github.com/nicolargo/glances/>`_.
 
+Ansible
+-------
+
+.. todo:: Write about Ansible
+
+    `Ansible Documentation
+    <http://www.ansibleworks.com/docs/>`_
+
 
 Chef
 ----

docs/scenarios/ci.rst

@@ -47,7 +47,7 @@ which provides the following features:
   interpreters
 * Running tests in each of the environments, configuring your test tool of
   choice
-* Acting as a frontend to Continuous Integration servers, reducing boilerplate
+* Acting as a front-end to Continuous Integration servers, reducing boilerplate
   and merging CI and shell-based testing.
 
 
@@ -65,11 +65,10 @@ example content::
 
     language: python
     python:
-      - "2.5"
       - "2.6"
       - "2.7"
-      - "3.1"
       - "3.2"
+      - "3.3"
     # command to install dependencies
     script: python tests/test_all_of_the_units.py
     branches:

docs/scenarios/cli.rst

@@ -6,7 +6,10 @@ Command Line Applications
 Clint
 -----
 
-.. todo:: Write about Clint
+`clint <https://pypi.python.org/pypi/clint/>`_ is a python module which is 
+filled with very useful tools for developing commandline applications.
+It supports features such as; CLI Colors and Indents, Simple and Powerful
+Column Printer, Iterator based progress bar and Implicit argument handling.
 
 docopt
 ------
@@ -14,3 +17,22 @@ docopt
 `docopt <http://docopt.org/>`_ is a lightweight, highly Pythonic package that
 allows creating command line interfaces easily and intuitively, by parsing
 POSIX-style usage instructions.
+
+Plac
+------
+
+`Plac <https://pypi.python.org/pypi/plac>`_ is a python module that allows developing command line applications. In fact 
+plac is a simple wrapper over the python standard library `argparse <http://docs.python.org/2/library/argparse.html>`_, it hides most of its 
+complexity by using a declarative interface: the argument parser is inferred 
+rather than written down by imperatively. It is targetting especially unsophisticated
+users, programmers, sys-admins, scientists and in general people writing throw-away
+scripts for themselves, choosing the command-line interface because it is quick
+and simple.
+
+Cliff
+------
+
+`Cliff <https://cliff.readthedocs.org/en/latest>`_  is a framework for building command line programs. 
+It uses setuptools entry points to provide subcommands, output formatters, and other extensions. The framework
+is meant to be used to create multi-level commands such as subversion and git, where the main program handles 
+some basic argument parsing and then invokes a sub-command to do the work.

docs/scenarios/db.rst

@@ -33,3 +33,11 @@ to provide database access.
 It's based on the idea of `models <https://docs.djangoproject.com/en/1.3/#the-model-layer>`_, an abstraction that makes it easier to
 manipulate data in Python.
 
+The basics:
+
+- Each model is a Python class that subclasses django.db.models.Model.
+- Each attribute of the model represents a database field.
+- Django gives you an automatically-generated database-access API; see `Making queries <https://docs.djangoproject.com/en/dev/topics/db/queries/>`__.
+to provide database access.
+
+

docs/scenarios/scientific.rst

@@ -9,7 +9,7 @@ Python is frequently used for high-performance scientific applications. Python
 is widely used in academia and scientific projects because it is easy to write,
 and it performs really well.
 
-Due to its high performance nature, scientific computing in python often refers
+Due to its high performance nature, scientific computing in Python often refers
 to external libraries, typically written in faster languages (like C, or
 FORTRAN for matrix operations). The main libraries used are `NumPy`_, `SciPy`_
 and `Matplotlib`_. Going into detail about these libraries is beyond the scope
@@ -24,11 +24,11 @@ Tools
 IPython
 -------
 
-`IPytthon <http://ipython.org/>`_ is an enhanced version of Python interpreter.
+`IPython <http://ipython.org/>`_ is an enhanced version of Python interpreter.
 The features it provides are of great interest for the scientists. The `inline mode`
 allow graphics and plots to be displayed in the terminal (Qt based version).
 Moreover the `notebook` mode supports literate programming and reproducible science
-generating a web-based python notebook. This notebook allowing to store chunk of
+generating a web-based Python notebook. This notebook allowing to store chunk of
 Python code along side to the results and additional comments (HTML, LaTeX, Markdown).
 The notebook could be shared and exported in various file formats.
 
@@ -53,9 +53,10 @@ NumPy is compatible with Python versions 2.4 through to 2.7.2 and 3.1+.
 
 Numba
 -----
-Numba is an Numpy aware Python compiler (just-in-time (JIT) specializing 
+
-compiler) which compiles annotated Python (and Numpy) code to LLVM (Low Level 
+`Numba <http://numba.pydata.org>`_ is an Numpy aware Python compiler
-Virtual Machine) (through special decorators). 
+(just-in-time (JIT) specializing compiler) which compiles annotated Python (and
+Numpy) code to LLVM (Low Level Virtual Machine) (through special decorators).
 Briefly, Numba using system that compiles Python code with LLVM to code which
 can be natively executed at runtime.
 
@@ -64,7 +65,7 @@ SciPy
 
 `SciPy <http://scipy.org/>`_ is a library that uses Numpy for more mathematical
 functions. SciPy uses NumPy arrays as the basic data structure. SciPy comes
-with modules for various commonly used tasks in scientific programing, for
+with modules for various commonly used tasks in scientific programming, for
 example: linear algebra, integration (calculus), ordinary differential equation
 solvers and signal processing.
 
@@ -86,7 +87,7 @@ based on Numpy and which provides many useful functions for accessing,
 indexing, merging and grouping data easily. The main data structure (DataFrame)
 is close to what could be found in the R statistical package, that is
 an heterogeneous data tables with name indexing, time series operations
-and auto-alignement of data.
+and auto-alignment of data.
 
 Rpy2
 ----
@@ -120,7 +121,7 @@ Many people who do scientific computing are on Windows. And yet many of the
 scientific computing packages are notoriously difficult to build and install.
 `Christoph Gohlke <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_ however, has
 compiled a list of Windows binaries for many useful Python packages. The list
-of packages has grown from a mainly scientific python resource to a more
+of packages has grown from a mainly scientific Python resource to a more
 general list. It might be a good idea to check it out if you're on Windows.
 
 Enthought Python Distribution (EPD)

docs/scenarios/speed.rst

@@ -68,6 +68,140 @@ C Extensions
 Cython
 ------
 
+`Cython <http://cython.org/>`_ implements a superset of the Python language 
+with which you are able to write C and C++ modules for Python. Cython also 
+allows you to call functions from compiled C libraries. Using Cython allows 
+you to take advantage of Python's strong typing of variables and operations.  
+Here is an example of strong typing with Cython:
+
+.. code-block:: python
+
+    def primes(int kmax):
+    """Calculation of prime numbers with additional
+    Cython keywords"""
+
+        cdef int n, k, i
+        cdef int p[1000]
+        result = []
+        if kmax > 1000:
+            kmax = 1000
+        k = 0
+        n = 2
+        while k < kmax:
+            i = 0
+            while i < k and n % p[i] != 0:
+                i = i + 1
+            if i == k:
+                p[k] = n
+                k = k + 1
+                result.append(n)
+            n = n + 1
+        return result
+
+
+This implementation of an algorithm to find prime numbers has some additional keywords instead of the next one, which is implemented in pure Python:
+
+.. code-block:: python
+
+
+    def primes(kmax):
+    """Calculation of prime numbers in standard Python syntax"""
+
+        p= range(1000)
+        result = []
+        if kmax > 1000:
+            kmax = 1000
+        k = 0
+        n = 2
+        while k < kmax:
+            i = 0
+            while i < k and n % p[i] != 0:
+                i = i + 1
+            if i == k:
+                p[k] = n
+                k = k + 1
+                result.append(n)
+            n = n + 1
+        return result
+
+Notice that in the Cython version you declare integers and integer arrays for 
+to be compiled into C types while also creating a Python list:
+
+
+.. code-block:: python
+
+    def primes(int kmax):
+        """Calculation of prime numbers with additional
+        Cython keywords"""
+
+        cdef int n, k, i
+        cdef int p[1000]
+        result = []
+
+
+.. code-block:: python
+
+    def primes(kmax):
+        """Calculation of prime numbers in standard Python syntax"""
+
+        p= range(1000)
+        result = []
+
+What is the difference? In the upper Cython version you can see the declaration of the variable types  and the integer array
+in a similar way like in standard C. For example `cdef int n,k,i` in line 3.  This additional type declaration (e.g. integer)
+allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in `*.py` files,
+Cython code is saved in `*.pyx` files.
+
+And what is with the speed? So lets try it!
+
+.. code-block:: python
+
+	import time
+	#activate pyx compiler
+	import pyximport
+	pyximport.install()
+	#primes implemented with Cython
+	import primesCy
+	#primes implemented with Python
+	import primes
+
+	print "Cython:"
+	t1= time.time()
+	print primesCy.primes(500)
+	t2= time.time()
+	print "Cython time: %s" %(t2-t1)
+	print ""
+	print "Python"
+	t1= time.time()
+	print primes.primes(500)
+	t2= time.time()
+	print "Python time: %s" %(t2-t1)
+
+
+These both lines need a remark:
+
+.. code-block:: python
+
+    import pyximport
+    pyximport.install()
+
+
+The `pyximport` module allows you to import `pyx` files (e.g., `primesCy.pyx`) with the Cython-compiled version of the `primes` function.
+The `pyximport.install()` command allows the Python interpreter to start the Cython compiler directly to generate C-code,
+which is automatically compiled to a `*.so` C-library. Cython is able to import this library for you in your Python-code.
+Very easy and very efficient. With the `time.time()` function you are able to compare the time between this 2 different calls to find 500 prime numbers.
+
+On a standard notebook (dualcore AMD E-450 1,6 GHz)  the measured values are:
+
+Cython time: 0.0054 seconds
+
+Python time: 0.0566 seconds
+
+And here the output of an embedded `ARM beaglebone <http://beagleboard.org/Products/BeagleBone>`_  machine:
+
+Cython time: 0.0196 seconds
+
+Python time: 0.3302 seconds
 
 Pyrex
 -----

docs/scenarios/web.rst

@@ -271,10 +271,10 @@ and to the templates themselves.
   templates. This convenience can lead to uncontrolled
   increase in complexity, and often harder to find bugs.
 
-- It is often necessary to mix javascript templates with
+- It is often necessary to mix JavaScript templates with
   HTML templates. A sane approach to this design is to isolate
   the parts where the HTML template passes some variable content
-  to the javascript code.
+  to the JavaScript code.
 
 
 
@@ -370,7 +370,7 @@ The `base.html` file can be used as base for all site pages which are for exampl
     </body>
 
 
-The next listing is our site page (`site.html`) loaded in the python app which extends `base.html`. The content block is
+The next listing is our site page (`site.html`) loaded in the Python app which extends `base.html`. The content block is
 automatically set into the corresponding block in the base.html page.
 
 .. code-block:: html

docs/scenarios/xml.rst

@@ -4,11 +4,11 @@ XML parsing
 untangle
 --------
 
-`untangle <http://0chris.com/untangle>`_ is a simple library which takes
+`untangle <https://github.com/stchris/untangle>`_ is a simple library which
-an XML document and returns a Python object which mirrors the nodes and
+takes an XML document and returns a Python object which mirrors the nodes and
 attributes in its structure.
 
-For example, an xml file like this:
+For example, an XML file like this:
 
 .. code-block:: xml
 
@@ -36,9 +36,9 @@ xmltodict
 ---------
 
 `xmltodict <http://github.com/martinblech/xmltodict>`_ is another simple
-library that aims at making xml feel like working with json.
+library that aims at making XML feel like working with JSON.
 
-An xml file like this:
+An XML file like this:
 
 .. code-block:: xml
 
@@ -52,7 +52,7 @@ An xml file like this:
       </plus>
     </mydocument>
 
-can be loaded into a python dict like this:
+can be loaded into a Python dict like this:
 
 .. code-block:: python
 
@@ -68,6 +68,6 @@ and then you can access elements, attributes and values like this:
     doc['mydocument']['plus']['@a'] # == u'complex'
     doc['mydocument']['plus']['#text'] # == u'element as well'
 
-xmltodict also lets you roundtrip back to xml with the unparse function,
+xmltodict also lets you roundtrip back to XML with the unparse function,
 has a streaming mode suitable for handling files that don't fit in memory
 and supports namespaces.

docs/shipping/packaging.rst

@@ -5,6 +5,8 @@ Packaging your code is important.
 
 You'll need to package your code first before sharing it with other developers.
 
+The `Python Packaging Guide <https://python-packaging-user-guide.readthedocs.org/en/latest/>`_ provides an extensive guide on creating and maintaining Python packages.
+
 For Python Developers
 :::::::::::::::::::::
 
@@ -44,7 +46,7 @@ Go to your command prompt and type:
    $ python -m SimpleHTTPServer 9000
 
 This runs a simple http server running on port 9000 and will list all packages
-(like **MyPackage**). Now you can install **MyPackage** using any python
+(like **MyPackage**). Now you can install **MyPackage** using any Python
 package installer. Using Pip, you would do it like:
 
 .. code-block:: console
@@ -60,17 +62,49 @@ you can still install MyPackage using:
 
    $ pip install  http://127.0.0.1:9000/MyPackage.tar.gz
 
-Chishop
+pypiserver
-+++++++
+++++++++++
 
-`Chishop <https://github.com/benliles/djangopypi>`_ is a simple PyPI server
+`Pypiserver <https://pypi.python.org/pypi/pypiserver>`_ is a minimal PyPI compatible server.
-written in django which allows you to register/upload with distutils and
+It can be used to serve a set of packages to easy_install or pip.  It includes helpful
-install with easy_install/pip.
+features like an administrative command (``-U``) which will update all its packages to their
+latest versions found on PyPI.
+
+
+S3-Hosted PyPi
+++++++++++++++
+
+One simple option for a personal PyPi server is to use Amazon S3. A prerequisite for this is that you have an Amazon AWS account with an S3 bucket.
+
+1. **Install all your requirements from PyPi or another source**
+2. **Install pip2pi**
+
+* :code:`pip install git+https://github.com/wolever/pip2pi.git`
+
+3. **Follow pip2pi README for pip2tgz and dir2pi commands**
+
+* :code:`pip2tgz packages/ YourPackage` (or :code:`pip2tgz packages/ -r requirements.txt`)
+* :code:`dir2pi packages/`
+
+4. **Upload the new files**
+
+* Use a client like Cyberduck to sync the entire :code:`packages` folder to your s3 bucket
+* Make sure you upload :code:`packages/simple/index.html` as well as all new files and directories
+
+5. **Fix new file permissions**
+
+* By default, when you upload new files to the S3 bucket, they will have the wrong permissions set.
+* Use the Amazon web console to set the READ permission of the files to EVERYONE.
+* If you get HTTP 403 when trying to install a package, make sure you've set the permissions correctly.
+
+6. **All done**
+
+* You can now install your package with :code:`pip install --index-url=http://your-s3-bucket/packages/simple/ YourPackage`
 
 For Linux Distributions
 ::::::::::::::::::::::::
 
-* `Ubuntu <https://wiki.ubuntu.com/PackagingGuide/Python>`_
+* `Ubuntu <http://packaging.ubuntu.com/html/python-packaging.html>`_
 * `Fedora <https://fedoraproject.org/wiki/Packaging:Python>`_
 * `Debian <http://www.debian.org/doc/packaging-manuals/python-policy/>`_
 * `Arch <https://wiki.archlinux.org/index.php/Python_Package_Guidelines>`_
@@ -78,5 +112,5 @@ For Linux Distributions
 Useful Tools
 ------------
 
-- epm
+- `fpm <https://github.com/jordansissel/fpm>`_
-- alien
+- `alien <http://joeyh.name/code/alien/>`_

docs/starting/install/osx.rst

@@ -3,7 +3,7 @@
 Installing Python on Mac OS X
 =============================
 
-The latest version of Mac OS X, Mountain Lion, **comes with Python 2.7 out of the box**.
+The latest version of Mac OS X, Mavericks, **comes with Python 2.7 out of the box**.
 
 You do not need to install or configure anything else to use Python. Having
 said that, I would strongly recommend that you install the tools and libraries
@@ -33,14 +33,14 @@ package.
 
 While Lion comes with a large number of UNIX utilities, those familiar with
 Linux systems will notice one key component missing: a decent package manager.
-`Homebrew <http://mxcl.github.com/homebrew/>`_ fills this void.
+`Homebrew <http://brew.sh>`_ fills this void.
 
-To `install Homebrew <https://github.com/mxcl/homebrew/wiki/installation>`_,
+To `install Homebrew <https://github.com/Homebrew/homebrew/wiki/installation>`_,
 simply run
 
 .. code-block:: console
 
-    $ ruby -e "$(curl -fsSL https://raw.github.com/mxcl/homebrew/go)"
+    $ ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)" 
 
 The script will explain what changes it will make and prompt you before the
 installation begins.
@@ -50,7 +50,7 @@ line at the bottom of your ``~/.bashrc`` file
 
 .. code-block:: console
 
-    export PATH=/usr/local/bin:$PATH
+    export PATH=/usr/local/bin:/usr/local/sbin:$PATH
 
 Now, we can install Python 2.7: ::
 
@@ -96,9 +96,9 @@ habit of using it to create completely clean Python environments for each
 project. This is particularly important for Web development, where each
 framework and application will have many dependencies.
 
-To set up a new Python environment, change the working directory to where ever
+To set up a new Python environment, move into the directory where you would 
-you want to store the environment, and run the virtualenv utility in your
+like to store the environment, and use the ``virtualenv`` utility to create 
-project's directory
+the new environment.
 
 .. code-block:: console
 

docs/starting/install/win.rst

@@ -3,7 +3,7 @@
 Installing Python on Windows
 ============================
 
-First, download the `latest version <http://python.org/ftp/python/2.7.4/python-2.7.4.msi>`_
+First, download the `latest version <http://python.org/ftp/python/2.7.6/python-2.7.6.msi>`_
 of Python 2.7 from the official Website. If you want to be sure you are installing a fully
 up-to-date version then use the "Windows Installer" link from the home page of the
 `Python.org web site <http://python.org>`_ .
@@ -80,7 +80,7 @@ project. This is particularly important for Web development, where each
 framework and application will have many dependencies.
 
 
-To set up a new Python environment, change the working directory to where ever
+To set up a new Python environment, change the working directory to wherever
 you want to store the environment, and run the virtualenv utility in your
 project's directory
 

docs/starting/which-python.rst

@@ -47,11 +47,11 @@ level of compatibility with Python packages and C extension modules.
 
 If you are writing open-source Python code and want to reach the widest possible
 audience, targeting CPython is your best bet. If you need to use any packages
-that rely on C extensions for their functionality (e.g. numpy) then CPython
+that rely on C extensions for their functionality (e.g., numpy) then CPython
 is your only choice.
 
 Being the reference implementation, all versions of the Python language are
-available as CPython. Python 3 is only available as a CPython implementation.
+available as CPython.
 
 PyPy
 ----
@@ -67,13 +67,14 @@ If you are looking to squeeze more performance out of your Python code, it's
 worth giving PyPy a try. On a suite of benchmarks, it's currently `over 5 times
 faster than CPython <http://speed.pypy.org/>`_.
 
-Currently PyPy supports Python 2.7. [#pypy_ver]_
+Currently PyPy supports Python 2.7. PyPy3 which targets Python 3 was recently
+available as a beta release. [#pypy_ver]_
 
 Jython
 ------
 
 `Jython <http://www.jython.org/>`_ is a Python implementation that compiles
-Python code to Java byte code that is then executed in a JVM. It has the additional
+Python code to Java bytecode that is then executed in a JVM. It has the additional
 advantage of being able to import and use any Java class like a Python
 module.
 

docs/writing/documentation.rst

@@ -94,7 +94,9 @@ Reference`_ should help you familiarize yourself with its syntax.
 Code Documentation Advice
 -------------------------
 
-Comments clarify code and begin with a hash (``#``).
+Comments clarify the code and they are added with purpose of making the 
+code easier to understand. In Python, comments begin with a hash 
+(number sign) (``#``).
 
 .. _docstring-ref:
 
@@ -160,3 +162,9 @@ Epydoc_
     Epydoc is discontinued. Use :ref:`sphinx-ref` instead.
 
 .. _Epydoc: http://epydoc.sourceforge.net
+
+MkDocs_
+    MkDocs is a fast and simple static site generator that's geared towards 
+    building project documentation with Markdown.
+
+.. _MkDocs: http://www.mkdocs.org/

docs/writing/license.rst

@@ -48,5 +48,5 @@ To help you choose one for your project, there's a `license chooser <http://thre
   + GPLv2
   + GPLv3
 
-
+A good overview of licenses with explanations of what one can, cannot, and must do using a particular software can be found at `tl;drLegal <https://tldrlegal.com/>`_.
 

docs/writing/structure.rst

@@ -14,7 +14,7 @@ isolated? By answering questions like these you can begin to plan, in
 a broad sense, what your finished product will look like.
 
 In this section we take a closer look at Python's module and import
-systems as they are the central element to enforcing structure in your
+systems as they are the central elements to enforcing structure in your
 project. We then discuss various perspectives on how to build code which
 can be extended and tested reliably.
 
@@ -94,7 +94,7 @@ be sure to avoid using special symbols like the dot (.) or question mark (?).
 So a file name like `my.spam.py` is one you should avoid! Naming this way
 will interfere with the way python looks for modules.
 
-In this example python expects to find a "spam.py" file in a folder named "my"
+In the case of `my.spam.py` python expects to find a "spam.py" file in a folder named "my"
 which is not the case. There is an
 `example <http://docs.python.org/tutorial/modules.html#packages>`_ of how the
 dot notation should be used in the python docs.

docs/writing/style.rst

@@ -434,7 +434,7 @@ Check if variable equals a constant
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You don't need to explicitly compare a value to True, or None, or 0 - you can
-just add it to the if statement. See :ref:`Truth Value Testing
+just add it to the if statement. See `Truth Value Testing
 <http://docs.python.org/library/stdtypes.html#truth-value-testing>`_ for a
 list of what is considered false.
 

docs/writing/tests.rst

@@ -40,7 +40,7 @@ Some general rules of testing:
 - If you are in the middle of a development session and have to interrupt your work, it
   is a good idea to write a broken unit test about what you want to develop next.
   When coming back to work, you will have a pointer to where you were and get
-  faster on tracks.
+  back on track faster.
 
 - The first step when you are debugging your code is to write a new test
   pinpointing the bug. While it is not always possible to do, those bug