diff options
Diffstat (limited to 'docs/conventions.rst')
| -rw-r--r-- | docs/conventions.rst | 114 |
1 files changed, 0 insertions, 114 deletions
diff --git a/docs/conventions.rst b/docs/conventions.rst deleted file mode 100644 index 21b506623..000000000 --- a/docs/conventions.rst +++ /dev/null @@ -1,114 +0,0 @@ -Typographical Conventions -========================= - -Literals, filenames and function arguments are presented using the -following style: - - ``argument1`` - -Warnings, which represent limitations and need-to-know information -related to a topic or concept are presented in the following style: - - .. warning:: - - This is a warning. - -Notes, which represent additional information related to a topic or -concept are presented in the following style: - - .. note:: - - This is a note. - -We present Python method names using the following style: - - :meth:`pyramid.config.Configurator.add_view` - -We present Python class names, module names, attributes and global -variables using the following style: - - :class:`pyramid.config.Configurator.registry` - -References to glossary terms are presented using the following style: - - :term:`Pylons` - -URLs are presented using the following style: - - `Pylons <http://pylonsproject.org>`_ - -References to sections and chapters are presented using the following -style: - - :ref:`traversal_chapter` - -Code and configuration file blocks are presented in the following style: - - .. code-block:: python - :linenos: - - def foo(abc): - pass - -Example blocks representing UNIX shell commands are prefixed with a ``$`` -character, e.g.: - - .. code-block:: text - - $ $VENV/bin/nosetests - -(See :term:`virtualenv` for the meaning of ``$VENV``) - -Example blocks representing Windows ``cmd.exe`` commands are prefixed with a -drive letter and/or a directory name, e.g.: - - .. code-block:: text - - c:\examples> %VENV%\Scripts\nosetests - -(See :term:`virtualenv` for the meaning of ``%VENV%``) - -Sometimes, when it's unknown which directory is current, Windows ``cmd.exe`` -example block commands are prefixed only with a ``>`` character, e.g.: - - .. code-block:: text - - > %VENV%\Scripts\nosetests - -When a command that should be typed on one line is too long to fit on a page, -the backslash ``\`` is used to indicate that the following printed line -should actually be part of the command: - - .. code-block:: text - - c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ - --cover-erase --with-coverage - -A sidebar, which presents a concept tangentially related to content -discussed on a page, is rendered like so: - -.. sidebar:: This is a sidebar - - Sidebar information. - -When multiple objects are imported from the same package, -the following convention is used: - - .. code-block:: python - - from foo import ( - bar, - baz, - ) - -It may look unusual, but it has advantages: - -* It allows one to swap out the higher-level package ``foo`` for something - else that provides the similar API. An example would be swapping out - one Database for another (e.g. graduating from SQLite to PostgreSQL). - -* Looks more neat in cases where a large number of objects get imported from - that package. - -* Adding/removing imported objects from the package is quicker and results - in simpler diffs. |
