Change filename to :file:filename throughout (pypa#458)

Author: Rebecca Turner

source/discussions/install-requires-vs-requirements.rst

@@ -11,10 +11,10 @@ install_requires vs Requirements files
 install_requires
 ----------------
 
-``install_requires`` is a :ref:`setuptools` ``setup.py`` keyword that should be
-used to specify what a project **minimally** needs to run correctly.  When the
-project is installed by :ref:`pip`, this is the specification that is used to
-install its dependencies.
+``install_requires`` is a :ref:`setuptools` :file:`setup.py` keyword that
+should be used to specify what a project **minimally** needs to run correctly.
+When the project is installed by :ref:`pip`, this is the specification that is
+used to install its dependencies.
 
 For example, if the project requires A and B, your ``install_requires`` would be
 like so:

source/guides/creating-and-discovering-plugins.rst

@@ -105,11 +105,11 @@ but it's not recommended to make your project's main top-level package (
 ``myapp`` in this case) a namespace package for the purpose of plugins, as one
 bad plugin could cause the entire namespace to break which would in turn make
 your project unimportable. For the "namespace sub-package" approach to work,
-the plugin packages must omit the ``__init__.py`` for your top-level package
-directory (``myapp`` in this case) and include the namespace-package style
-``__init__.py`` in the namespace sub-package directory (``myapp/plugins``).
-This also means that plugins will need to explicitly pass a list of packages
-to :func:`setup`'s ``packages`` argument instead of using
+the plugin packages must omit the :file:`__init__.py` for your top-level
+package directory (``myapp`` in this case) and include the namespace-package
+style :file:`__init__.py` in the namespace sub-package directory
+(``myapp/plugins``).  This also means that plugins will need to explicitly pass
+a list of packages to :func:`setup`'s ``packages`` argument instead of using
 :func:`setuptools.find_packages`.
 
 .. warning:: Namespace packages are a complex feature and there are several
@@ -121,11 +121,11 @@ Using package metadata
 ======================
 
 `Setuptools`_ provides `special support`_ for plugins. By
-providing the ``entry_points`` argument to :func:`setup` in ``setup.py``
+providing the ``entry_points`` argument to :func:`setup` in :file:`setup.py`
 plugins can register themselves for discovery.
 
 For example if you have a package named ``myapp-plugin-a`` and it includes
-in its ``setup.py``:
+in its :file:`setup.py`:
 
 .. code-block:: python
 
@@ -156,9 +156,9 @@ In this example, ``plugins`` would be :
         'a': <module: 'myapp_plugin_a'>,
     }
 
-.. note:: The ``entry_point`` specification in ``setup.py`` is fairly flexible
-    and has a lot of options. It's recommended to read over the entire section
-    on `entry points`_.
+.. note:: The ``entry_point`` specification in :file:`setup.py` is fairly
+    flexible and has a lot of options. It's recommended to read over the entire
+    section on `entry points`_.
 
 .. _Setuptools: http://setuptools.readthedocs.io
 .. _special support:

source/guides/installing-using-pip-and-virtualenv.rst

@@ -337,7 +337,7 @@ Using requirements files
 
 Instead of installing packages individually, pip allows you to declare all
 dependencies in a :ref:`Requirements File <pip:Requirements Files>`. For
-example you could create a ``requirements.txt`` file containing:
+example you could create a :file:`requirements.txt` file containing:
 
 .. code-block:: text
 

source/guides/packaging-namespace-packages.rst

@@ -81,7 +81,7 @@ Native namespace packages
 
 Python 3.3 added **implicit** namespace packages from :pep:`420`. All that is
 required to create a native namespace package is that you just omit
-``__init__.py`` from the namespace package directory. An example file
+:file:`__init__.py` from the namespace package directory. An example file
 structure:
 
 .. code-block:: text
@@ -95,13 +95,13 @@ structure:
             module.py
 
 It is extremely important that every distribution that uses the namespace
-package omits the ``__init__.py`` or uses a pkgutil-style ``__init__.py``. If
-any distribution does not, it will cause the namespace logic to fail and the
-other sub-packages will not be importable.
+package omits the :file:`__init__.py` or uses a pkgutil-style
+:file:`__init__.py`. If any distribution does not, it will cause the namespace
+logic to fail and the other sub-packages will not be importable.
 
-Because ``mynamespace`` doesn't contain an ``__init__.py``,
+Because ``mynamespace`` doesn't contain an :file:`__init__.py`,
 :func:`setuptools.find_packages` won't find the sub-package. You must
-explicitly list all packages in your ``setup.py``. For example:
+explicitly list all packages in your :file:`setup.py`. For example:
 
 .. code-block:: python
 
@@ -133,7 +133,7 @@ packages that need to be compatible with both Python 2.3+ and Python 3. This
 is the recommended approach for the highest level of compatibility.
 
 To create a pkgutil-style namespace package, you need to provide an
-``__init__.py`` file for the namespace package:
+:file:`__init__.py` file for the namespace package:
 
 .. code-block:: text
 
@@ -144,17 +144,17 @@ To create a pkgutil-style namespace package, you need to provide an
             __init__.py  # Sub-package __init__.py
             module.py
 
-The ``__init__.py`` file for the namespace package needs to contain **only**
-the following:
+The :file:`__init__.py` file for the namespace package needs to contain
+**only** the following:
 
 .. code-block:: python
 
     __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
 **Every** distribution that uses the namespace package must include an
-identical ``__init__.py``. If any distribution does not, it will cause the
-namespace logic to fail and the other sub-packages will not be importable. Any
-additional code in ``__init__.py`` will be inaccessible.
+identical :file:`__init__.py`. If any distribution does not, it will cause the
+namespace logic to fail and the other sub-packages will not be importable.  Any
+additional code in :file:`__init__.py` will be inaccessible.
 
 A complete working example of two pkgutil-style namespace packages can be found
 in the `pkgutil namespace example project`_.
@@ -179,7 +179,7 @@ methods are not cross-compatible and it's not advisable to try to migrate an
 existing package.
 
 To create a pkg_resources-style namespace package, you need to provide an
-``__init__.py`` file for the namespace package:
+:file:`__init__.py` file for the namespace package:
 
 .. code-block:: text
 
@@ -190,20 +190,20 @@ To create a pkg_resources-style namespace package, you need to provide an
             __init__.py  # Sub-package __init__.py
             module.py
 
-The ``__init__.py`` file for the namespace package needs to contain **only**
-the following:
+The :file:`__init__.py` file for the namespace package needs to contain
+**only** the following:
 
 .. code-block:: python
 
     __import__('pkg_resources').declare_namespace(__name__)
 
 **Every** distribution that uses the namespace package must include an
-identical ``__init__.py``. If any distribution does not, it will cause the
-namespace logic to fail and the other sub-packages will not be importable. Any
-additional code in ``__init__.py`` will be inaccessible.
+identical :file:`__init__.py`. If any distribution does not, it will cause the
+namespace logic to fail and the other sub-packages will not be importable.  Any
+additional code in :file:`__init__.py` will be inaccessible.
 
 .. note:: Some older recommendations advise the following in the namespace
-    package ``__init__.py``:
+    package :file:`__init__.py`:
 
     .. code-block:: python
 
@@ -220,7 +220,7 @@ additional code in ``__init__.py`` will be inaccessible.
     ``install_requires``.
 
 Finally, every distribution must provide the ``namespace_packages`` argument
-to :func:`~setuptools.setup` in ``setup.py``. For example:
+to :func:`~setuptools.setup` in :file:`setup.py`. For example:
 
 .. code-block:: python
 

source/guides/single-sourcing-package-version.rst

@@ -8,9 +8,10 @@ Single-sourcing the package version
 There are many techniques to maintain a single source of truth for the version
 number of your project:
 
-#.  Read the file in ``setup.py`` and parse the version with a regex. Example (
-    from `pip setup.py <https://github.com/pypa/pip/blob/master/setup.py#L12>`_)::
-    
+#.  Read the file in :file:`setup.py` and parse the version with a regex.
+    Example ( from `pip setup.py
+    <https://github.com/pypa/pip/blob/master/setup.py#L12>`_)::
+
         here = os.path.abspath(os.path.dirname(__file__))
 
         def read(*parts):
@@ -44,8 +45,8 @@ number of your project:
 
 
 #.  Set the value to a ``__version__`` global variable in a dedicated module in
-    your project (e.g. ``version.py``), then have ``setup.py`` read and ``exec`` the
-    value into a variable.
+    your project (e.g. :file:`version.py`), then have :file:`setup.py` read and
+    ``exec`` the value into a variable.
 
     Using ``execfile``:
 
@@ -66,8 +67,8 @@ number of your project:
 
     Example using this technique: `warehouse <https://github.com/pypa/warehouse/blob/master/warehouse/__about__.py>`_.
 
-#.  Place the value in a simple ``VERSION`` text file and have both ``setup.py``
-    and the project code read it.
+#.  Place the value in a simple ``VERSION`` text file and have both
+    :file:`setup.py` and the project code read it.
 
     ::
 
@@ -81,9 +82,9 @@ number of your project:
 
         With this approach you must make sure that the ``VERSION`` file is included in
         all your source and binary distributions (e.g. add ``include VERSION`` to your
-        ``MANIFEST.in``).
+        :file:`MANIFEST.in`).
 
-#.  Set the value in ``setup.py``, and have the project code use the
+#.  Set the value in :file:`setup.py`, and have the project code use the
     ``pkg_resources`` API.
 
     ::
@@ -97,7 +98,7 @@ number of your project:
 
 
 #.  Set the value to ``__version__`` in ``sample/__init__.py`` and import
-    ``sample`` in ``setup.py``.
+    ``sample`` in :file:`setup.py`.
 
     ::
 
@@ -110,8 +111,8 @@ number of your project:
 
     Although this technique is common, beware that it will fail if
     ``sample/__init__.py`` imports packages from ``install_requires``
-    dependencies, which will very likely not be installed yet when ``setup.py``
-    is run.
+    dependencies, which will very likely not be installed yet when
+    :file:`setup.py` is run.
 
 
 #.  Keep the version number in the tags of a version control system (Git, Mercurial, etc)

source/guides/supporting-windows-using-appveyor.rst

@@ -54,9 +54,9 @@ Adding Appveyor support to your project
 =======================================
 
 In order to define how Appveyor should build your project, you need to add an
-``appveyor.yml`` file to your project. The full details of what can be included
-in the file are covered in the Appveyor documentation. This guide will provide
-the details necessary to set up wheel builds.
+:file:`appveyor.yml` file to your project. The full details of what can be
+included in the file are covered in the Appveyor documentation. This guide will
+provide the details necessary to set up wheel builds.
 
 Appveyor includes by default all of the compiler toolchains needed to build
 extensions for Python. For Python 2.7, 3.5+ and 32-bit versions of 3.3 and 3.4,
@@ -74,7 +74,7 @@ appveyor.yml
 
 This file can be downloaded from `here <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/appveyor-sample/appveyor.yml>`__.
 
-The ``appveyor.yml`` file must be located in the root directory of your
+The :file:`appveyor.yml` file must be located in the root directory of your
 project. It is in ``YAML`` format, and consists of a number of sections.
 
 The ``environment`` section is the key to defining the Python versions for
@@ -101,10 +101,10 @@ The ``test_script`` section is where you will run your project's tests. The
 supplied file runs your test suite using ``setup.py test``. If you are only
 interested in building wheels, and not in running your tests on Windows, you
 can replace this section with a dummy command such as ``echo Skipped Tests``.
-You may wish to use another test tool, such as ``nose`` or ``py.test``. Or you
-may wish to use a test driver like ``tox`` - however if you are using ``tox``
-there are some additional configuration changes you will need to consider,
-which are described below.
+You may wish to use another test tool, such as ``nose`` or :file:`py.test`.  Or
+you may wish to use a test driver like ``tox`` - however if you are using
+``tox`` there are some additional configuration changes you will need to
+consider, which are described below.
 
 The ``after_test`` runs once your tests have completed, and so is where the
 wheels should be built. Assuming your project uses the recommended tools
@@ -118,10 +118,10 @@ tests to fail on Windows, you can skip them as described above.
 Support script
 --------------
 
-The ``appveyor.yml`` file relies on a single support script, which sets up the
-environment to use the SDK compiler for 64-bit builds on Python 3.3 and 3.4.
-For projects which do not need a compiler, or which don't support 3.3 or 3.4 on
-64-bit Windows, only the ``appveyor.yml`` file is needed.
+The :file:`appveyor.yml` file relies on a single support script, which sets up
+the environment to use the SDK compiler for 64-bit builds on Python 3.3 and
+3.4.  For projects which do not need a compiler, or which don't support 3.3 or
+3.4 on 64-bit Windows, only the :file:`appveyor.yml` file is needed.
 
 `build.cmd <https://raw.githubusercontent.com/pypa/python-packaging-user-guide/master/source/guides/appveyor-sample/build.cmd>`__
 is a Windows batch script that runs a single command in an environment with the
@@ -172,10 +172,11 @@ other CI systems).
         - ``INCLUDE``
         - ``LIB``
 
-    The ``passenv`` option can be set in your ``tox.ini``, or if you prefer to avoid
-    adding Windows-specific settings to your general project files, it can be set by
-    setting the ``TOX_TESTENV_PASSENV`` environment variable. The supplied ``build.cmd``
-    script does this by default whenever ``DISTUTILS_USE_SDK`` is set.
+    The ``passenv`` option can be set in your :file:`tox.ini`, or if you prefer
+    to avoid adding Windows-specific settings to your general project files, it
+    can be set by setting the ``TOX_TESTENV_PASSENV`` environment variable. The
+    supplied :file:`build.cmd` script does this by default whenever
+    ``DISTUTILS_USE_SDK`` is set.
 
 2. When used interactively, ``tox`` allows you to run your tests against multiple
    environments (often, this means multiple Python versions). This feature is not as
@@ -194,33 +195,35 @@ other CI systems).
     will be run with the configured interpreter.
 
     In order to support running under the ``py`` environment, it is possible that
-    projects with complex ``tox`` configurations might need to modify their ``tox.ini``
-    file. Doing so is, however, outside the scope of this document.
+    projects with complex ``tox`` configurations might need to modify their
+    :file:`tox.ini` file. Doing so is, however, outside the scope of this
+    document.
 
 Automatically uploading wheels
 ------------------------------
 
 It is possible to request Appveyor to automatically upload wheels. There is a
-``deployment`` step available in ``appveyor.yml`` that can be used to (for
+``deployment`` step available in :file:`appveyor.yml` that can be used to (for
 example) copy the built artifacts to a FTP site, or an Amazon S3 instance.
 Documentation on how to do this is included in the Appveyor guides.
 
 Alternatively, it would be possible to add a ``twine upload`` step to the
-build.  The supplied ``appveyor.yml`` does not do this, as it is not clear that
-uploading new wheels after every commit is desirable (although some projects
-may wish to do this).
+build.  The supplied :file:`appveyor.yml` does not do this, as it is not clear
+that uploading new wheels after every commit is desirable (although some
+projects may wish to do this).
 
 External dependencies
 ---------------------
 
 The supplied scripts will successfully build any distribution that does not
 rely on 3rd party external libraries for the build.
 
-It is possible to add steps to the ``appveyor.yml`` configuration (typically
-in the "install" section) to download and/or build external libraries needed by
-the distribution. And if needed, it is possible to add extra configuration for
-the build to supply the location of these libraries to the compiler. However,
-this level of configuration is beyond the scope of this document.
+It is possible to add steps to the :file:`appveyor.yml` configuration
+(typically in the "install" section) to download and/or build external
+libraries needed by the distribution. And if needed, it is possible to add
+extra configuration for the build to supply the location of these libraries to
+the compiler. However, this level of configuration is beyond the scope of this
+document.
 
 
 Support scripts

source/key_projects.rst

@@ -100,9 +100,9 @@ Pipfile
 
 `Source <https://github.com/pypa/pipfile>`__
 
-``Pipfile`` and its sister ``Pipfile.lock`` are a higher-level
+:file:`Pipfile` and its sister :file:`Pipfile.lock` are a higher-level
 application-centric alternative to :ref:`pip`'s lower-level
-``requirements.txt`` file.
+:file:`requirements.txt` file.
 
 
 Python Packaging User Guide
@@ -332,11 +332,11 @@ pex
 `Github <https://github.com/pantsbuild/pex/>`__ |
 `PyPI <https://pypi.python.org/pypi/pex>`__
 
-pex is both a library and tool for generating ``.pex`` (Python EXecutable)
+pex is both a library and tool for generating :file:`.pex` (Python EXecutable)
 files, standalone Python environments in the spirit of :ref:`virtualenv`.
-``.pex`` files are just carefully constructed zip files with a
-``#!/usr/bin/env python`` and special ``__main__.py``, and are designed to make
-deployment of Python applications as simple as ``cp``.
+:file:`.pex` files are just carefully constructed zip files with a
+``#!/usr/bin/env python`` and special :file:`__main__.py`, and are designed to
+make deployment of Python applications as simple as ``cp``.
 
 
 .. _spack: