Mark up files & directories

docs/dev/env.rst

@@ -16,7 +16,7 @@ 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
+:pep:`8`. In your home directory, open a file called :file:`.vimrc` and add the
 following lines::
 
     set textwidth=79  " lines longer than 79 columns will be broken
@@ -46,7 +46,7 @@ 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`::
 
     autocmd BufWritePost *.py call Pyflakes()
     autocmd BufWritePost *.py call Pep8()
@@ -253,7 +253,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

docs/dev/virtualenvs.rst

@@ -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:
 
@@ -94,7 +94,7 @@ 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:
 
@@ -105,6 +105,7 @@ This creates the ``venv`` folder inside ``~/Envs``.
 **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
 can quickly switch between environments.
 
@@ -128,19 +129,19 @@ Other useful commands
 
 ``cdvirtualenv``
   Navigate into the directory of the currently activated virtual environment,
-  so you can browse its ``site-packages``, for example.
+  so you can browse its :file:`site-packages`, for example.
 
 ``cdsitepackages``
-  Like the above, but directly into ``site-packages`` directory.
+  Like the above, but directly into :file:`site-packages` directory.
 
 ``lssitepackages``
-  Shows contents of ``site-packages`` directory.
+  Shows contents of :file:`site-packages` directory.
 
 `Full list of virtualenvwrapper commands <http://virtualenvwrapper.readthedocs.org/en/latest/command_ref.html>`_.
 
 autoenv
 -------
-When you ``cd`` into a directory containing a ``.env``, `autoenv <https://github.com/kennethreitz/autoenv>`_
+When you ``cd`` into a directory containing a :file:`.env`, `autoenv <https://github.com/kennethreitz/autoenv>`_
 automagically activates the environment.
 
 Install it on Mac OS X using ``brew``:

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

docs/scenarios/ci.rst

@@ -60,7 +60,7 @@ 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
+In order to get started, add a :file:`.travis.yml` file to your repository with this
 example content::
 
     language: python

docs/scenarios/speed.rst

@@ -150,8 +150,8 @@ to be compiled into C types while also creating a Python list:
 
 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.
+allows the Cython compiler to generate more efficient C code from the second code. While standard Python code is saved in :file:`*.py` files,
+Cython code is saved in :file:`*.pyx` files.
 
 And what is with the speed? So lets try it!
 
@@ -187,9 +187,9 @@ These both lines need a remark:
     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` module allows you to import :file:`*.pyx` files (e.g., :file:`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.
+which is automatically compiled to a :file:`*.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 (dual core AMD E-450 1.6 GHz), the measured values are:
 

docs/scenarios/web.rst

@@ -252,7 +252,7 @@ Gondor
 `Gondor <https://gondor.io/>`_ is a PaaS specialized for deploying Django
 and Pinax applications. Gondor supports Django versions 1.2 and 1.3 on
 Python version 2.7, and can automatically configure your Django site if you
-use ``local_settings.py`` for site-specific configuration information.
+use :file:`local_settings.py` for site-specific configuration information.
 
 Gondor has a guide on deploying `Django projects <https://gondor.io/support/django/setup/>`_.
 
@@ -365,7 +365,7 @@ to use.
         application.listen(PORT)
         tornado.ioloop.IOLoop.instance().start()
 
-The `base.html` file can be used as base for all site pages which are for example implemented in the content block.
+The :file:`base.html` file can be used as base for all site pages which are for example implemented in the content block.
 
 .. code-block:: html
 
@@ -389,8 +389,8 @@ 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
-automatically set into the corresponding block in the base.html page.
+The next listing is our site page (:file:`site.html`) loaded in the Python app which extends :file:`base.html`. The content block is
+automatically set into the corresponding block in the :file:`base.html` page.
 
 .. code-block:: html
 

docs/shipping/freezing.rst

@@ -38,7 +38,7 @@ cx_Freeze   yes     yes   yes  yes      PSF     no            yes            yes
 .. note::
     All solutions need MS Visual C++ dll to be installed on target machine.
     Only Pyinstaller makes self-executable exe that bundles the dll when
-    passing ``--onefile`` to `Configure.py`.
+    passing ``--onefile`` to :file:`Configure.py`.
 
 Windows
 -------
@@ -72,7 +72,7 @@ Prerequisite is to install :ref:`Python on Windows <install-windows>`.
 
 4. (Optionally) `one-file mode <http://stackoverflow.com/questions/112698/py2exe-generate-single-executable-file#113014>`_
 
-5. Generate ``.exe`` into ``dist`` directory:
+5. Generate :file:`.exe` into :file:`dist` directory:
 
 .. code-block:: console
 

docs/shipping/packaging.rst

@@ -30,7 +30,7 @@ running from the directory which holds those packages which need to be installed
 
 **Showing an example is always beneficial**
 
-Say if you are after installing a package called MyPackage.tar.gz,  and
+Say if you are after installing a package called :file:`MyPackage.tar.gz`,  and
 assuming this is your directory structure:
 
 
@@ -55,7 +55,7 @@ package installer. Using Pip, you would do it like:
 
 Having a folder with the same name as the package name is **crucial** here.
 I got fooled by that, one time. But if you feel that creating a folder called
-**MyPackage** and keeping **MyPackage.tar.gz** inside that, is *redundant*,
+:file:`MyPackage` and keeping :file:`MyPackage.tar.gz` inside that, is *redundant*,
 you can still install MyPackage using:
 
 .. code-block:: console
@@ -88,7 +88,7 @@ One simple option for a personal PyPi server is to use Amazon S3. A prerequisite
 
 4. **Upload the new files**
 
-* Use a client like Cyberduck to sync the entire :code:`packages` folder to your s3 bucket
+* Use a client like Cyberduck to sync the entire :file:`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**

docs/starting/install/osx.rst

@@ -47,7 +47,7 @@ The script will explain what changes it will make and prompt you before the
 installation begins.
 Once you've installed Homebrew, insert the Homebrew directory at the top
 of your ``PATH`` environment variable. You can do this by adding the following
-line at the bottom of your ``~/.bashrc`` file
+line at the bottom of your :file:`~/.bashrc` file
 
 .. code-block:: console
 

docs/starting/install/win.rst

@@ -13,7 +13,7 @@ double-click the file. The MSI package format allows Windows administrators to
 automate installation with their standard tools.
 
 By design, Python installs to a directory with the version number embedded,
-e.g. Python version 2.7 will install at ``C:\Python27\``, so that you can
+e.g. Python version 2.7 will install at :file:`C:\Python27\`, so that you can
 have multiple versions of Python on the
 same system without conflicts. Of course, only one interpreter can be the
 default application for Python file types. It also does not automatically
@@ -22,7 +22,7 @@ which copy of Python is run.
 
 Typing the full path name for a Python interpreter each time quickly gets
 tedious, so add the directories for your default Python version to the PATH.
-Assuming that your Python installation is in ``C:\Python27\``, add this to your
+Assuming that your Python installation is in :file:`C:\Python27\`, add this to your
 PATH:
 
 .. code-block:: console
@@ -35,7 +35,7 @@ You can do this easily by running the following in ``powershell``:
 
     [Environment]::SetEnvironmentVariable("Path", "$env:Path;C:\Python27\;C:\Python27\Scripts\", "User")
 
-The second (``Scripts``) directory receives command files when certain
+The second (:file:`Scripts`) directory receives command files when certain
 packages are installed, so it is a very useful addition.
 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
@@ -92,14 +92,14 @@ project's directory
 
     > virtualenv venv
 
-To use an environment, run the ``activate.bat`` batch file in the ``Scripts``
+To use an environment, run the :file:`activate.bat` batch file in the :file:`Scripts`
 subdirectory of that environment. Your command prompt will change to show the
 active environment. Once you have finished working in the current virtual
-environment, run the ``deactivate.bat`` batch file to restore your settings to
+environment, run the :file:`deactivate.bat` batch file to restore your settings to
 normal.
 
 Each new environment automatically includes a copy of ``pip`` in the
-``Scripts`` subdirectory, so that you can setup the third-party libraries and
+:file:`Scripts` subdirectory, so that you can setup the third-party libraries and
 tools that you want to use in that environment. Put your own code within a
 subdirectory of the environment, however you wish. When you no longer need a
 particular environment, simply copy your code out of it, and then delete the

docs/starting/pip-virtualenv.rst

@@ -18,13 +18,13 @@ project. Over time this can result in a messy global package list.
 
 In order to make sure that you install packages to your active virtual environment
 when you use ``pip install``, consider adding the following two lines to your
-``~/.bashrc`` file:
+:file:`~/.bashrc` file:
 
 .. code-block:: console
 
     export PIP_REQUIRE_VIRTUALENV=true
 
-After saving this change and sourcing the ``~/.bashrc`` file with ``source ~/.bashrc``,
+After saving this change and sourcing the :file:`~/.bashrc` file with ``source ~/.bashrc``,
 pip will no longer let you install packages if you are not in a virtual environment.
 If you try to use ``pip install`` outside of a virtual environment pip will gently
 remind you that an activated virtual environment is needed to install packages.
@@ -34,22 +34,22 @@ remind you that an activated virtual environment is needed to install packages.
     $ pip install requests
     Could not find an activated virtualenv (required).
 
-You can also do this configuration by editing your ``pip.conf`` or ``pip.ini``
-file. ``pip.conf`` is used by Unix and Mac OS X operating systems and it can be
+You can also do this configuration by editing your :file:`pip.conf` or :file:`pip.ini`
+file. :file:`pip.conf` is used by Unix and Mac OS X operating systems and it can be
 found at:
 
 .. code-block:: console
 
     $HOME/.pip/pip.conf
 
-Similarly, the ``pip.ini`` file is used by Windows operating systems and it can
+Similarly, the :file:`pip.ini` file is used by Windows operating systems and it can
 be found at:
 
 .. code-block:: console
 
     %HOME%\pip\pip.ini
 
-If you don't have a ``pip.conf`` or ``pip.ini`` file at these locations, you can
+If you don't have a :file:`pip.conf` or :file:`pip.ini` file at these locations, you can
 create a new file with the correct name for your operating system.
 
 If you already have a configuration file, just add the following line under the
@@ -70,7 +70,7 @@ add the following lines to this new file:
 
 You will of course need to install some packages globally (usually ones that you
 use across different projects consistenly) and this can be accomplished by adding
-the following to your ``~/.bashrc`` file:
+the following to your :file:`~/.bashrc` file:
 
 .. code-block:: console
 
@@ -78,7 +78,7 @@ the following to your ``~/.bashrc`` file:
         PIP_REQUIRE_VIRTUALENV="" pip "$@"
     }
 
-After saving the changes and sourcing your ``~/.bashrc`` file you can now install
+After saving the changes and sourcing your :file:`~/.bashrc` file you can now install
 packages globally by running ``gpip install``. You can change the name of the
 function to anything you like, just keep in mind that you will have to use that
 name when trying to install packages globally with pip.
@@ -96,7 +96,7 @@ start working on a new project (and in a new virtual environmen as a result).
 Fortunately, you can configure pip in such a way that it tries to reuse already
 installed packages.
 
-On UNIX systems, you can add the following line to your ``.bashrc`` or ``.bash_profile``
+On UNIX systems, you can add the following line to your :file:`.bashrc` or :file:`.bash_profile`
 file.
 
 .. code-block:: console
@@ -104,25 +104,25 @@ file.
     export PIP_DOWNLOAD_CACHE=$HOME/.pip/cache
 
 You can set the path to anywhere you like (as long as you have write
-access). After adding this line, ``source`` your ``.bashrc`` (or ``.bash_profile``)
+access). After adding this line, ``source`` your :file:`.bashrc` (or :file:`.bash_profile`)
 file and you will be all set.
 
-Another way of doing the same configuration is via the ``pip.conf`` or ``pip.ini``
+Another way of doing the same configuration is via the :file:`pip.conf` or :file:`pip.ini`
 files, depending on your system. If you are on Windows, you can add the following
-line to your ``pip.ini`` file under ``[global]`` settings:
+line to your :file:`pip.ini` file under ``[global]`` settings:
 
 .. code-block:: console
 
     download-cache = %HOME%\pip\cache
 
 Similarly, on UNIX systems you should simply add the following line to your
-``pip.conf`` file under ``[global]`` settings:
+:file:`pip.conf` file under ``[global]`` settings:
 
 .. code-block:: console
 
     download-cache = $HOME/.pip/cache
 
 Even though you can use any path you like to store your cache, it is recommended
-that you create a new folder *in* the folder where your ``pip.conf`` or ``pip.ini``
+that you create a new folder *in* the folder where your :file:`pip.conf` or :file:`pip.ini`
 file lives. If you don't trust yourself with all of this path voodoo, just use
 the values provided here and you will be fine.

docs/writing/documentation.rst

@@ -8,7 +8,7 @@ both you and others a lot of time.
 Project Documentation
 ---------------------
 
-A ``README`` file at the root directory should give general
+A :file:`README` file at the root directory should give general
 information to the users and the maintainers. It should be raw text or
 written in some very easy to read markup, such as
 :ref:`reStructuredText-ref` and Markdown. It should contain a few
@@ -17,18 +17,18 @@ assuming the user knows anything about the project), the url of the
 main source for the software, and some basic credit information. This
 file is the main entry point for readers of the code.
 
-An ``INSTALL`` file is less necessary with python.  The installation
+An :file:`INSTALL` file is less necessary with python.  The installation
 instructions are often reduced to one command, such as ``pip install
-module`` or ``python setup.py install`` and added to the ``README``
+module`` or ``python setup.py install`` and added to the :file:`README`
 file.
 
-A ``LICENSE`` file should *always* be present and specify the license under which the
+A :file:`LICENSE` file should *always* be present and specify the license under which the
 software is made available to the public.
 
-A ``TODO`` file or a ``TODO`` section in ``README`` should list the
+A :file:`TODO` file or a ``TODO`` section in :file:`README` should list the
 planned development for the code.
 
-A ``CHANGELOG`` file or section in ``README`` should compile a short
+A :file:`CHANGELOG` file or section in :file:`README` should compile a short
 overview of the changes in the code base for the latest versions.
 
 Project Publication

docs/writing/structure.rst

@@ -34,7 +34,7 @@ to do it poorly. Some signs of a poorly structured project
 include:
 
 - Multiple and messy circular dependencies: if your classes
-  Table and Chair in furn.py need to import Carpenter from workers.py
+  Table and Chair in :file:`furn.py` need to import Carpenter from :file:`workers.py`
   to answer a question such as ``table.isdoneby()``,
   and if conversely the class Carpenter needs to import Table and Chair,
   to answer the question ``carpenter.whatdo()``, then you
@@ -91,15 +91,15 @@ environment, or your project's internal modules.
 
 To keep in line with the style guide, keep module names short, lowercase, and
 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
+So a file name like :file:`my.spam.py` is one you should avoid! Naming this way
 will interfere with the way python looks for modules.
 
-In the case of `my.spam.py` 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 :file:`spam.py` file in a folder named :file:`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.
 
-If you'd like you could name it as `my_spam.py` but even our friend the
+If you'd like you could name it as :file:`my_spam.py` but even our friend the
 underscore should not be seen often in module names.
 
 Aside for some naming restrictions, nothing special is required for a Python file
@@ -107,12 +107,12 @@ to be a module, but the import mechanism needs to be understood in order to use
 this concept properly and avoid some issues.
 
 Concretely, the ``import modu`` statement will look for the proper file, which is
-`modu.py` in the same directory as the caller if it exists.  If it is not
-found, the Python interpreter will search for `modu.py` in the "path"
+:file:`modu.py` in the same directory as the caller if it exists.  If it is not
+found, the Python interpreter will search for :file:`modu.py` in the "path"
 recursively and raise an ImportError exception if it is not found.
 
-Once `modu.py` is found, the Python interpreter will execute the module in an
-isolated scope. Any top-level statement in `modu.py` will be executed,
+Once :file:`modu.py` is found, the Python interpreter will execute the module in an
+isolated scope. Any top-level statement in :file:`modu.py` will be executed,
 including other imports if any. Function and class definitions are stored in
 the module's dictionary.
 
@@ -176,24 +176,24 @@ Packages
 Python provides a very straightforward packaging system, which is simply an
 extension of the module mechanism to a directory.
 
-Any directory with an __init__.py file is considered a Python package. The
+Any directory with an :file:`__init__.py` file is considered a Python package. The
 different modules in the package are imported in a similar manner as plain
-modules, but with a special behavior for the __init__.py file, which is used to
+modules, but with a special behavior for the :file:`__init__.py` file, which is used to
 gather all package-wide definitions.
 
-A file modu.py in the directory pack/ is imported with the statement `import
-pack.modu`. This statement will look for an __init__.py file in `pack`, execute
-all of its top-level statements. Then it will look for a file `pack/modu.py` and
+A file :file:`modu.py` in the directory :file:`pack/` is imported with the statement `import
+pack.modu`. This statement will look for an :file:`__init__.py` file in :file:`pack`, execute
+all of its top-level statements. Then it will look for a file :file:`pack/modu.py` and
 execute all of its top-level statements. After these operations, any variable,
-function, or class defined in modu.py is available in the pack.modu namespace.
+function, or class defined in :file:`modu.py` is available in the pack.modu namespace.
 
-A commonly seen issue is to add too much code to __init__.py
+A commonly seen issue is to add too much code to :file:`__init__.py`
 files. When the project complexity grows, there may be sub-packages and
 sub-sub-packages in a deep directory structure, and then, importing a single item
-from a sub-sub-package will require executing all __init__.py files met while
+from a sub-sub-package will require executing all :file:`__init__.py` files met while
 traversing the tree.
 
-Leaving an __init__.py file empty is considered normal and even a good practice,
+Leaving an :file:`__init__.py` file empty is considered normal and even a good practice,
 if the package's modules and sub-packages do not need to share any code.
 
 Lastly, a convenient syntax is available for importing deeply nested packages: