diff --git a/docs/dev/env.rst b/docs/dev/env.rst index 3610307aa..aa63fee4e 100644 --- a/docs/dev/env.rst +++ b/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 diff --git a/docs/dev/virtualenvs.rst b/docs/dev/virtualenvs.rst index cf2b285b9..3f07cfec8 100644 --- a/docs/dev/virtualenvs.rst +++ b/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 `_. autoenv ------- -When you ``cd`` into a directory containing a ``.env``, `autoenv `_ +When you ``cd`` into a directory containing a :file:`.env`, `autoenv `_ automagically activates the environment. Install it on Mac OS X using ``brew``: diff --git a/docs/scenarios/admin.rst b/docs/scenarios/admin.rst index 26dc5e6a4..85fd5b8f5 100644 --- a/docs/scenarios/admin.rst +++ b/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 diff --git a/docs/scenarios/ci.rst b/docs/scenarios/ci.rst index 962c6c866..7138893ec 100644 --- a/docs/scenarios/ci.rst +++ b/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 diff --git a/docs/scenarios/speed.rst b/docs/scenarios/speed.rst index bee6769df..96065c200 100644 --- a/docs/scenarios/speed.rst +++ b/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: diff --git a/docs/scenarios/web.rst b/docs/scenarios/web.rst index 2d2ab5171..8a15ae9f1 100644 --- a/docs/scenarios/web.rst +++ b/docs/scenarios/web.rst @@ -252,7 +252,7 @@ Gondor `Gondor `_ 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 `_. @@ -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 -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 diff --git a/docs/shipping/freezing.rst b/docs/shipping/freezing.rst index d114d741d..a54ea95b1 100644 --- a/docs/shipping/freezing.rst +++ b/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 `. 4. (Optionally) `one-file mode `_ -5. Generate ``.exe`` into ``dist`` directory: +5. Generate :file:`.exe` into :file:`dist` directory: .. code-block:: console diff --git a/docs/shipping/packaging.rst b/docs/shipping/packaging.rst index d2757f049..84ba67c3e 100644 --- a/docs/shipping/packaging.rst +++ b/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** diff --git a/docs/starting/install/osx.rst b/docs/starting/install/osx.rst index cdd8b3259..ea991e6af 100644 --- a/docs/starting/install/osx.rst +++ b/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 diff --git a/docs/starting/install/win.rst b/docs/starting/install/win.rst index d84084f77..7f98b0bd9 100644 --- a/docs/starting/install/win.rst +++ b/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 diff --git a/docs/starting/pip-virtualenv.rst b/docs/starting/pip-virtualenv.rst index a910ae75f..b632c2b5b 100644 --- a/docs/starting/pip-virtualenv.rst +++ b/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. diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 29de3e40c..b52fca7c4 100644 --- a/docs/writing/documentation.rst +++ b/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 diff --git a/docs/writing/structure.rst b/docs/writing/structure.rst index 6ebd5d8f4..358972093 100644 --- a/docs/writing/structure.rst +++ b/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 `_ 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: