Mark up files & directories

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: