Getting up-to-date before pushing changes

Author: Can Ibanoglu

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 "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/osxpython"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/pythonguide"
+	@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 @@ <h3>Useful Links</h3>
   <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
-test script, this provides sequential steps to learning python.
+teaching basic Python concepts.  By fixing assertion statements that fail in a
+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
-choosen from mathematics and the natural sciences.
+mainly covers Python's usage in scientific field. In the book, examples are
+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
-emphasis on numerical methods and how to implement them in python.
+Numerical Methods in Engineering with Python, written by Jaan Kiusalaas, attempts to
+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/>`_