From 545654d60719161bdde4633afa42704cd5fedde5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 19 Mar 2012 00:06:48 -0400 Subject: explain where things might go in reality and explain gt example Windows convention --- docs/conventions.rst | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 9e8510e4d..0c38e11d8 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -50,9 +50,30 @@ Code and configuration file blocks are presented in the following style: def foo(abc): pass -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: +Example blocks representing UNIX shell commands are prefixed with a ``$`` +character, e.g.: + + .. code-block:: text + + $ ../bin/nosetests + +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> ..\Scripts\nosetests + +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 + + > ..\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 -- cgit v1.2.3 From f73f0e332658fac2583f51247dcd49bd36d63ce4 Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Wed, 13 Mar 2013 23:05:17 +0200 Subject: consistency: use $VENV whenever virtualenv binaries are used --- docs/conventions.rst | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 0c38e11d8..4cffd1084 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -55,21 +55,25 @@ character, e.g.: .. code-block:: text - $ ../bin/nosetests + $ $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> ..\Scripts\nosetests + 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 - > ..\Scripts\nosetests + > %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 @@ -77,7 +81,7 @@ should actually be part of the command: .. code-block:: text - c:\bigfntut\tutorial> ..\Scripts\nosetests --cover-package=tutorial \ + c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ --cover-erase --with-coverage A sidebar, which presents a concept tangentially related to content -- cgit v1.2.3 From d886c933784e499a6243b0ebbfc04fb0bb2be4fa Mon Sep 17 00:00:00 2001 From: Tshepang Lekhonkhobe Date: Mon, 25 Mar 2013 12:16:39 +0200 Subject: mention a coding convention --- docs/conventions.rst | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 4cffd1084..21b506623 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -91,3 +91,24 @@ discussed on a page, is rendered like so: 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. -- cgit v1.2.3 From c1677348ad92a7998ae1163c3e2f7b38942849c2 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 28 May 2015 02:23:56 -0700 Subject: grammar, punctuation --- docs/conventions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 21b506623..0492ab4fd 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -1,19 +1,19 @@ Typographical Conventions ========================= -Literals, filenames and function arguments are presented using the +Literals, filenames, and function arguments are presented using the following style: ``argument1`` -Warnings, which represent limitations and need-to-know information +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 +Notes which represent additional information related to a topic or concept are presented in the following style: .. note:: @@ -105,7 +105,7 @@ 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). + 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. -- cgit v1.2.3 From 3eada22d7f2baff2c13acc3ca6b2388f6b9dbd80 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 4 Oct 2015 00:59:19 -0700 Subject: grammar --- docs/conventions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 0492ab4fd..a9d2550bf 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -24,7 +24,7 @@ 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 +We present Python class names, module names, attributes, and global variables using the following style: :class:`pyramid.config.Configurator.registry` @@ -105,10 +105,10 @@ 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). + 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 +* Adding or removing imported objects from the package is quicker and results in simpler diffs. -- cgit v1.2.3 From d67566acebf890a603fad0e9069d5e131dfb5b31 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 12 Apr 2016 06:43:38 -0700 Subject: one does not simply "create a virtualenv". one should "create a virtual environment". - Fixes #2483 --- docs/conventions.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index a9d2550bf..0346f1107 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -57,7 +57,7 @@ character, e.g.: $ $VENV/bin/nosetests -(See :term:`virtualenv` for the meaning of ``$VENV``) +(See :term:`venv` 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.: @@ -66,7 +66,7 @@ drive letter and/or a directory name, e.g.: c:\examples> %VENV%\Scripts\nosetests -(See :term:`virtualenv` for the meaning of ``%VENV%``) +(See :term:`venv` 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.: -- cgit v1.2.3 From 1ceb14546a6f82b886f45c256379a2ef3897c6a5 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 Apr 2016 14:10:14 -0700 Subject: replace nose with pytest, clean up --- docs/conventions.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 0346f1107..5164b5479 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -53,46 +53,46 @@ Code and configuration file blocks are presented in the following style: Example blocks representing UNIX shell commands are prefixed with a ``$`` character, e.g.: - .. code-block:: text + .. code-block:: bash - $ $VENV/bin/nosetests + $ $VENV/bin/py.test tutorial/tests.py -q (See :term:`venv` 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 + .. code-block:: doscon - c:\examples> %VENV%\Scripts\nosetests + c:\examples> %VENV%\Scripts\py.test tutorial\tests.py -q (See :term:`venv` 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 + .. code-block:: doscon > %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: +the backslash ``\`` is used to indicate that the following printed line should +be part of the command: - .. code-block:: text + .. code-block:: bash - c:\bigfntut\tutorial> %VENV%\Scripts\nosetests --cover-package=tutorial \ - --cover-erase --with-coverage + $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: +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: +When multiple objects are imported from the same package, the following +convention is used: .. code-block:: python @@ -103,9 +103,9 @@ the following convention is used: 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). +* 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. -- cgit v1.2.3 From 88eebf18615d7b301bc443b6da031768bba9a831 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 16 Apr 2016 14:12:36 -0700 Subject: missed yer nose! --- docs/conventions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/conventions.rst') diff --git a/docs/conventions.rst b/docs/conventions.rst index 5164b5479..4469d0c73 100644 --- a/docs/conventions.rst +++ b/docs/conventions.rst @@ -73,7 +73,7 @@ example block commands are prefixed only with a ``>`` character, e.g.: .. code-block:: doscon - > %VENV%\Scripts\nosetests + > %VENV%\Scripts\py.test tutorial\tests.py -q 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 -- cgit v1.2.3