Enhanced markup

Readme.rst

@@ -26,7 +26,7 @@ Topics include:
 - Server configurations & tools for various web frameworks
 - Documentation: writing it
 - Testing: Jenkins & tox guides
-- How to easily interface ``hg`` from ``git`` easily
+- How to easily interface :program:`hg` from :program:`git` easily
 
 If you aren't fond of reading reStructuredText, there is an
 almost up-to-date `HTML version at docs.python-guide.org

docs/dev/env.rst

@@ -16,8 +16,10 @@ Vim is a text editor which uses keyboard shortcuts for editing instead of menus
 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::
+:pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the
+following lines:
+
+.. code-block:: 
 
     set textwidth=79  " lines longer than 79 columns will be broken
     set shiftwidth=4  " operation >> indents 4 columns; << unindents 4 columns
@@ -38,22 +40,26 @@ the syntax file included in VIM 6.1.
 These plugins supply you with a basic environment for developing in Python.
 To get the most out of Vim, you should continually check your code for syntax
 errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
-If your VIM is compiled with `+python` you can also utilize some very handy
+If your VIM is compiled with :option:`+python` you can also utilize some very handy
 plugins to do these checks from within the editor.
 
 For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
 install vim-pyflakes_. Now you can map the functions ``Pep8()`` or ``Pyflakes()``
 to any hotkey or action you want in Vim. Both plugins will display errors at
 the bottom of the screen, and provide an easy way to jump to the corresponding
 line. It's very handy to call these functions whenever you save a file. In
-order to do this, add the following lines to your ``.vimrc``::
+order to do this, add the following lines to your :file:`.vimrc`:
+
+.. code-block:: 
 
     autocmd BufWritePost *.py call Pyflakes()
     autocmd BufWritePost *.py call Pep8()
 
 If you are already using syntastic_ you can enable it to run Pyflakes on write
 and show errors and warnings in the quickfix window. An example configuration
-to do that which also shows status and warning messages in the statusbar would be::
+to do that which also shows status and warning messages in the statusbar would be:
+
+.. code-block:: 
 
     set statusline+=%#warningmsg#
     set statusline+=%{SyntasticStatuslineFlag()}
@@ -67,10 +73,10 @@ Python-mode
 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
-- Code refactoring and autocompletion with Rope
+- Asynchronous Python code checking (:program:`pylint`, :program:`pyflakes`, :program:`pep8`, :program:`mccabe`) in any combination
+- Code refactoring and autocompletion with :program:`rope`
 - Fast Python folding
-- Virtualenv support
+- :program:`virtualenv` support
 - Search by Python documentation and run Python code
 - Auto PEP8_ error fixes
 
@@ -186,7 +192,7 @@ Interpreter Tools
 virtualenv
 ----------
 
-Virtualenv is a tool to keep the dependencies required by different projects
+:program:`virtualenv` is a tool to keep the dependencies required by different projects
 in separate places, by creating virtual Python environments for them.
 It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
 dilemma, and keeps your global site-packages directory clean and manageable.
@@ -210,7 +216,7 @@ Create a virtual environment for a project:
     $ virtualenv venv
 
 ``virtualenv venv`` will create a folder in the current directory
-which will contain the Python executable files, and a copy of the ``pip``
+which will contain the Python executable files, and a copy of the :program:`pip`
 library which you can use to install other packages. The name of the
 virtual environment (in this case, it was ``venv``) can be anything;
 omitting the name will place the files in the current directory instead.
@@ -223,9 +229,9 @@ To start using the virtual environment, run:
 
 
 The name of the current virtual environment will now appear on the left
-of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
+of the prompt (e.g. :samp:`(venv){Your-Computer}:{your_project} {UserName}$`) to
 let you know that it's active. From now on, any package that you install
-using ``pip`` will be placed in the ``venv`` folder, isolated from the global
+using :program:`pip` will be placed in the :file:`venv` folder, isolated from the global
 Python installation. 
 
 Install packages as usual:
@@ -236,15 +242,15 @@ Install packages as usual:
 
 To stop using an environment, simply type ``deactivate``. To remove the
 environment, just remove the directory it was installed into. (In this
-case, it would be ``rm -rf venv``.)
+case, it would be :command:`rm -rf venv`.)
 
 Other Notes
 ^^^^^^^^^^^
 
-Running ``virtualenv`` with the option ``--no-site-packages`` will not
+Running :program:`virtualenv` with the option :option:`--no-site-packages` will not
 include the packages that are installed globally. This can be useful
 for keeping the package list clean in case it needs to be accessed later.
-[This is the default behavior for ``virtualenv`` 1.7 and later.]
+[This is the default behavior for :program:`virtualenv` 1.7 and later.]
 
 In order to keep your environment consistent, it's a good idea to "freeze"
 the current state of the environment packages. To do this, run
@@ -253,7 +259,7 @@ the current state of the environment packages. To do this, run
 
     $ pip freeze > requirements.txt
 
-This will create a ``requirements.txt`` file, which contains a simple
+This will create a :file:`requirements.txt` file, which contains a simple
 list of all the packages in the current environment, and their respective
 versions. Later, when a different developer (or you, if you need to re-
 create the environment) can install the same packages, with the same
@@ -280,15 +286,15 @@ virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
     $ pip install virtualenvwrapper
 
 
-Put this into your ``~/.bash_profile`` (Linux/Mac) file:
+Put this into your :file:`~/.bash_profile` (Linux/Mac) file:
 
 .. code-block:: console
 
     $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
 
-This will prevent your virtualenvs from relying on your (global) site packages
+This will prevent your virtualenvs from relying on your (global) :file:`site-packages`
 directory, so that they are completely separate..
-[note: This is the default behavior for ``virtualenv`` 1.7 and later]
+[note: This is the default behavior for :program:`virtualenv` 1.7 and later]
 
 Other Tools
 :::::::::::

docs/dev/virtualenvs.rst

@@ -14,7 +14,7 @@ virtualenv
 `virtualenv <http://pypi.python.org/pypi/virtualenv>`_ is a tool to create
 isolated Python environments.
 
-Install it via pip:
+Install it via :program:`pip`:
 
 .. code-block:: console
 
@@ -30,7 +30,7 @@ Basic Usage
    $ virtualenv venv
 
 This creates a copy of Python in whichever directory you ran the command in,
-placing it in a folder named ``venv``.
+placing it in a folder named :file:`venv`.
 
 2. To begin using the virtual environment, it needs to be activated:
 
@@ -64,7 +64,7 @@ virtualenvwrapper
 provides a set of commands which makes working with virtual environments much
 more pleasant. It also places all your virtual environments in one place.
 
-To install (make sure **virtualenv** is already installed):
+To install (make sure :program:`virtualenv` is already installed):
 
 .. code-block:: console
 
@@ -76,7 +76,7 @@ To install (make sure **virtualenv** is already installed):
 
 For Windows, you can use the `virtualenvwrapper-powershell <https://bitbucket.org/guillermooo/virtualenvwrapper-powershell>`_ clone.
 
-To install (make sure **virtualenv** is already installed):
+To install (make sure :program:`virtualenv` is already installed):
 
 .. code-block:: console
 
@@ -94,15 +94,15 @@ Basic Usage
 
    $ mkvirtualenv venv
 
-This creates the ``venv`` folder inside ``~/Envs``.
+This creates the :file:`venv` folder inside :file:`~/Envs`.
 
 2. Work on a virtual environment:
 
 .. code-block:: console
 
    $ workon venv
 
-**virtualenvwrapper** provides tab-completion on environment names. It really
+:program:`virtualenvwrapper` provides tab-completion on environment names. It really
 helps when you have a lot of environments and have trouble remembering their
 names.
 ``workon`` also deactivates whatever environment you are currently in, so you
@@ -140,10 +140,10 @@ Other useful commands
 
 autoenv
 -------
-When you ``cd`` into a directory containing a ``.env``, `autoenv <https://github.com/kennethreitz/autoenv>`_
+When you :command:`cd` into a directory containing :file:`.env`, `autoenv <https://github.com/kennethreitz/autoenv>`_
 automagically activates the environment.
 
-Install it on Mac OS X using ``brew``:
+Install it on Mac OS X using :program:`brew`:
 
 .. code-block:: console
 

docs/intro/duction.rst

@@ -11,7 +11,7 @@ include:
 
   Python's philosophy focuses on readability, from code blocks
   delineated with significant whitespace to intuitive keywords in
-  place of inscrutable punctuation
+  place of inscrutable punctuation.
 
 * **extensive standard libraries and third party modules for virtually
   any task**
@@ -41,7 +41,7 @@ include:
 * **ubiquity on computers**
 
   Python is available on Windows, \*nix, and Mac. It runs wherever the
-  Java virtual machine runs, and the reference implementation CPython
+  Java virtual machine runs, and the reference implementation :program:`CPython`
   can help bring Python to wherever there is a working C compiler.
 
 * **friendly community**
@@ -76,8 +76,8 @@ For the Community
 ~~~~~~~~~~~~~~~~~
 
 All contributions to the Guide are welcome, from Pythonistas of all levels.
-If you think there's a gap in what the Guide covers, fork the Guide on
-GitHub and submit a pull request. 
+If you think there's a gap in what The Guide covers, fork the Guide on
+GitHub and submit a pull request.
 
 Contributions are welcome from everyone, whether they're an old hand or a 
 first-time Pythonista, and the authors to the Guide will gladly help if you 

docs/intro/learning.rst

@@ -147,7 +147,7 @@ case-studies), method resolution order, using super() and meta-programming, and
 general :pep:`8` best practices.
 
 It has a detailed, multi-chapter case study on writing and releasing a package
-and eventually an application, including a chapter on using zc.buildout.  Later
+and eventually an application, including a chapter on using :module:`zc.buildout`.  Later
 chapters detail best practices with writing documentation, test-driven
 development, version control, and optimization/profiling.
 

docs/notes/styleguide.rst

@@ -99,7 +99,7 @@ Python interpreter examples:
 
     Label the example::
 
-    .. code-block:: python
+    .. code-block:: pycon
 
         >>> import this
 

docs/scenarios/admin.rst

@@ -38,7 +38,7 @@ server.
                 run('git pull')
                 run('touch app.wsgi')
 
-With the previous code saved in a file named fabfile.py, we can check memory
+With the previous code saved in a file named :file:`fabfile.py`, we can check memory
 usage with:
 
 .. code-block:: console
@@ -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:
+:program:`Salt` supports Python versions 2.6 and 2.7 and can be installed via :program:`pip`:
 
 .. code-block:: console
 
@@ -86,7 +86,7 @@ Salt supports Python versions 2.6 and 2.7 and can be installed via pip:
 After configuring a master server and any number of minion hosts, we can run arbitrary
 shell commands or use pre-built modules of complex commands on our minions.
 
-The following command lists all available minion hosts, using the ping module.
+The following command lists all available minion hosts, using the :module:`ping` module.
 
 .. code-block:: console
 
@@ -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>`_
 

docs/scenarios/ci.rst

@@ -60,8 +60,10 @@ Requests whether this particular changeset breaks the build or not. So if you ar
 hosting your code on Github, travis-ci is a great and easy way to get started with
 Continuous Integration.
 
-In order to get started, add a ``.travis.yml`` file to your repository with this
-example content::
+In order to get started, add a :file:`.travis.yml` file to your repository with this
+example content.
+
+.. code-block:: yaml
 
     language: python
     python:

docs/scenarios/client.rst

@@ -13,15 +13,15 @@ foundation of data communication for the World Wide Web.
 Requests
 --------
 
-Python’s standard urllib2 module provides most of the HTTP capabilities you
+Python’s standard :module:`urllib2` module provides most of the HTTP capabilities you
 need, but the API is thoroughly broken. It was built for a different time —
 and a different web. It requires an enormous amount of work (even method
 overrides) to perform the simplest of tasks.
 
 Requests takes all of the work out of Python HTTP — making your integration
 with web services seamless. There’s no need to manually add query strings to
 your URLs, or to form-encode your POST data. Keep-alive and HTTP connection
-pooling are 100% automatic, powered by urllib3, which is embedded within
+pooling are 100% automatic, powered by :module:`urllib3`, which is embedded within
 Requests.
 
 - `Documentation <http://docs.python-requests.org/en/latest/index.html>`_

docs/scenarios/db.rst

@@ -6,8 +6,8 @@ DB-API
 
 The Python Database API (DB-API) defines a standard interface for Python
 database access modules. It's documented in :pep:`249`.
-Nearly all Python database modules such as `sqlite3`, `psycopg` and
-`mysql-python` conform to this interface.
+Nearly all Python database modules (such as :module:`sqlite3`, 
+:module:`psycopg`, and :module:`mysql-python`) conform to this interface.
 
 Tutorials that explain how to work with modules that conform to this interface can be found
 `here <http://halfcooked.com/presentations/osdc2006/python_databases.html>`__ and
@@ -30,14 +30,12 @@ Django ORM
 The Django ORM is the interface used by `Django <http://www.djangoproject.com>`_
 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.
+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 model is a Python class that subclasses :module:`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/gui.rst

@@ -6,7 +6,7 @@ Alphabetical list of GUI Applications.
 Camelot
 -------
 `Camelot <http://www.python-camelot.com>`_ provides components for building 
-business applications on top of Python, SQLAlchemy and Qt.  It is inspired by 
+business applications on top of Python, SQLAlchemy, and Qt.  It is inspired by 
 the Django admin interface.  
 
 You can use Camelot to develop both simple and complex business applications 
@@ -36,7 +36,7 @@ interaction design and rapid prototyping, while making your code reusable
 and deployable.
 
 Kivy is written in Python, based on OpenGL and supports different input devices
-such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products and so on.
+such as: Mouse, Dual Mouse, TUIO, WiiMote, WM_TOUCH, HIDtouch, Apple's products, and so on.
 
 Kivy is actively being developed by a community and free to use. It operates
 on all major platforms (Linux, OSX, Windows, Android).
@@ -77,7 +77,7 @@ software with a GUI but can also be used for non-GUI applications.
 
 Tk
 --
-Tkinter is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
+:module:`Tkinter` is a thin object-oriented layer on top of Tcl/Tk. **It has the advantage
 of being included with the Python standard library, making it the most
 convenient and compatible toolkit to program with.**
 
@@ -91,7 +91,7 @@ available on the `Python Wiki <http://wiki.python.org/moin/TkInter>`_.
 
 wxPython
 --------
-wxPython is a GUI toolkit for the Python programming language. It allows
+:program:`wxPython` is a GUI toolkit for the Python programming language. It allows
 Python programmers to create programs with a robust, highly functional
 graphical user interface, simply and easily. It is implemented as a Python
 extension module (native code) that wraps the popular wxWidgets cross platform