From fb88f053a2a6ffaf3d597d49790fb19e956358e0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 02:15:23 -0800 Subject: Rename Typographical Conventions to Style Guide --- docs/conventions.rst | 107 -------------------------------------------------- docs/index.rst | 6 +-- docs/latexindex.rst | 2 +- docs/style-guide.rst | 109 +++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 113 insertions(+), 111 deletions(-) delete mode 100644 docs/conventions.rst create mode 100644 docs/style-guide.rst diff --git a/docs/conventions.rst b/docs/conventions.rst deleted file mode 100644 index de041da04..000000000 --- a/docs/conventions.rst +++ /dev/null @@ -1,107 +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 `_ - -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:: bash - - $ $VENV/bin/py.test -q - -See :term:`venv` for the meaning of ``$VENV``. - -Example blocks representing Windows commands are prefixed with a drive letter -with an optional directory name, e.g.: - - .. code-block:: doscon - - c:\examples> %VENV%\Scripts\py.test -q - -See :term:`venv` for the meaning of ``%VENV%``. - -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 -be part of the command: - - .. code-block:: bash - - $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ - --cov=tutorial -q - -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 or removing imported objects from the package is quicker and results - in simpler diffs. diff --git a/docs/index.rst b/docs/index.rst index 02c35866a..f41154c19 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -213,13 +213,13 @@ Copyright, Trademarks, and Attributions copyright -Typographical Conventions -========================= +Style Guide +=========== .. toctree:: :maxdepth: 1 - conventions + style-guide Index and Glossary diff --git a/docs/latexindex.rst b/docs/latexindex.rst index 05199d313..83a139917 100644 --- a/docs/latexindex.rst +++ b/docs/latexindex.rst @@ -15,7 +15,7 @@ Front Matter :maxdepth: 1 copyright - conventions + style-guide authorintro designdefense diff --git a/docs/style-guide.rst b/docs/style-guide.rst new file mode 100644 index 000000000..856d6ea85 --- /dev/null +++ b/docs/style-guide.rst @@ -0,0 +1,109 @@ +.. _style_guide: + +Style Guide +=========== + +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 `_ + +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:: bash + + $ $VENV/bin/py.test -q + +See :term:`venv` for the meaning of ``$VENV``. + +Example blocks representing Windows commands are prefixed with a drive letter +with an optional directory name, e.g.: + + .. code-block:: doscon + + c:\examples> %VENV%\Scripts\py.test -q + +See :term:`venv` for the meaning of ``%VENV%``. + +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 +be part of the command: + + .. code-block:: bash + + $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ + --cov=tutorial -q + +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 or removing imported objects from the package is quicker and results + in simpler diffs. -- cgit v1.2.3