diff options
| -rw-r--r-- | docs/conf.py | 1 | ||||
| -rw-r--r-- | docs/style-guide.rst | 276 |
2 files changed, 194 insertions, 83 deletions
diff --git a/docs/conf.py b/docs/conf.py index c3a7170fc..ace921247 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -68,6 +68,7 @@ intersphinx_mapping = { 'pylonswebframework': ('http://docs.pylonsproject.org/projects/pylons-webframework/en/latest/', None), 'python': ('https://docs.python.org/3', None), 'pytest': ('http://pytest.org/latest/', None), + 'sphinx': ('http://www.sphinx-doc.org/en/latest', None), 'sqla': ('http://docs.sqlalchemy.org/en/latest', None), 'tm': ('http://docs.pylonsproject.org/projects/pyramid-tm/en/latest/', None), 'toolbar': ('http://docs.pylonsproject.org/projects/pyramid-debugtoolbar/en/latest', None), diff --git a/docs/style-guide.rst b/docs/style-guide.rst index cb1a15be1..c30b199a6 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -5,7 +5,7 @@ Style Guide .. admonition:: description - This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. + This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. For coding style guidelines, see `Coding Style <http://docs.pylonsproject.org/en/latest/community/codestyle.html#coding-style>`_. .. _style-guide-introduction: @@ -146,18 +146,18 @@ Grammar, spelling, and capitalization preferences Use any commercial or free professional style guide in general. Use a spell- and grammar-checker. The following table lists the preferred grammar, spelling, and capitalization of words and phrases for frequently used items in the documentation. -========== ====================== -Preferred Avoid -========== ====================== -add-on addon -and so on etc. -GitHub Github, github -JavaScript Javascript, javascript -plug-in plugin -select check, tick (checkbox) -such as like -verify be sure -========== ====================== +========== ====================== +Preferred Avoid +========== ====================== +add-on addon +and so on etc. +GitHub Github, github +JavaScript Javascript, javascript +plug-in plugin +select check, tick (checkbox) +such as like +verify be sure +========== ====================== .. _style-guide-headings: @@ -228,12 +228,22 @@ The directive's sole argument is interpreted as the topic title, and next line m interpreted as body elements. +.. _style-guide-displaying-code: + +Displaying code +^^^^^^^^^^^^^^^ + +Code may be displayed in blocks or inline. You can include blocks of code from other source files. Blocks of code should use syntax highlighting. + +.. seealso:: See also the Sphinx documentation for :ref:`Showing code examples <sphinx:code-examples>`. + + .. _style-guide-syntax-highlighting: Syntax highlighting -^^^^^^^^^^^^^^^^^^^ +``````````````````` -Sphinx does syntax highlighting using the `Pygments <http://pygments.org/>`_ library. +Sphinx does syntax highlighting of code blocks using the `Pygments <http://pygments.org/>`_ library. Do not use two colons "::" at the end of a line, followed by a blank line, then indented code. Always specify the language to be used for syntax highlighting by using the ``code-block`` directive and indenting the code. @@ -253,17 +263,15 @@ XML: <somesnippet>Some XML</somesnippet> -Unix shell: +Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.) .. code-block:: rst .. code-block:: bash - # Start Plone in foreground mode for a test run - cd ~/Plone/zinstance - bin/plonectl fg + $ $VENV/bin/pip install -e . -Windows console: +Windows commands are prefixed with a drive letter with an optional directory name. (See :term:`venv` for the meaning of ``%VENV%``.) .. code-block:: rst @@ -271,6 +279,8 @@ Windows console: c:\> %VENV%\Scripts\pcreate -s starter MyProject + .. code-block:: doscon + cfg: .. code-block:: rst @@ -315,110 +325,210 @@ If syntax highlighting is not enabled for your code block, you probably have a s View the `full list of lexers and associated short names <http://pygments.org/docs/lexers/>`_. +.. _style-guide-long-commands: +Displaying long commands +```````````````````````` +When a command that should be typed on one line is too long to fit on the displayed width of a page, the backslash character ``\`` is used to indicate that the subsequent printed line should be part of the command: -Literals, filenames, and function arguments are presented using the -following style: + .. code-block:: rst - ``argument1`` + .. code-block:: bash -Warnings which represent limitations and need-to-know information -related to a topic or concept are presented in the following style: + $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ + --cov=tutorial -q - .. warning:: - This is a warning. +.. _style-guide-code-block-options: -Notes which represent additional information related to a topic or -concept are presented in the following style: +Code block options +`````````````````` - .. note:: +To emphasize lines (give the appearance that a highlighting pen has been used on the code), use the ``emphasize-lines`` option. The argument passed to ``emphasize-lines`` must be a comma-separated list of either single or ranges of line numbers. - This is a note. +.. code-block:: rst -We present Python method names using the following style: + .. code-block:: python + :emphasize-lines: 1,3 - :meth:`pyramid.config.Configurator.add_view` + if "foo" == "bar": + # This is Python code + pass -We present Python class names, module names, attributes, and global -variables using the following style: +The above code renders as follows. - :class:`pyramid.config.Configurator.registry` +.. code-block:: python + :emphasize-lines: 1,3 -References to glossary terms are presented using the following style: + if "foo" == "bar": + # This is Python code + pass - :term:`Pylons` +To display a code block with line numbers, use the ``linenos`` option. -URLs are presented using the following style: +.. code-block:: rst - `Pylons <http://www.pylonsproject.org>`_ + .. code-block:: python + :linenos: -References to sections and chapters are presented using the following -style: + if "foo" == "bar": + # This is Python code + pass - :ref:`traversal_chapter` +The above code renders as follows. -Code and configuration file blocks are presented in the following style: +.. code-block:: python + :linenos: - .. code-block:: python - :linenos: + if "foo" == "bar": + # This is Python code + pass - def foo(abc): - pass +Code blocks may be given a caption, which may serve as a filename or other description, using the ``caption`` option. They may also be given a ``name`` option, providing an implicit target name that can be referenced by using ``ref``. -Example blocks representing UNIX shell commands are prefixed with a ``$`` -character, e.g.: +.. code-block:: rst - .. code-block:: bash + .. code-block:: python + :caption: sample.py + :name: sample-py - $ $VENV/bin/py.test -q + if "foo" == "bar": + # This is Python code + pass -See :term:`venv` for the meaning of ``$VENV``. +The above code renders as follows. -Example blocks representing Windows commands are prefixed with a drive letter -with an optional directory name, e.g.: +.. code-block:: python + :caption: sample.py + :name: sample-py - .. code-block:: doscon + if "foo" == "bar": + # This is Python code + pass - c:\examples> %VENV%\Scripts\py.test -q +To specify the starting number to use for line numbering, use the ``lineno-start`` directive. -See :term:`venv` for the meaning of ``%VENV%``. +.. code-block:: rst -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:: python + :lineno-start: 2 - .. code-block:: bash + if "foo" == "bar": + # This is Python code + pass - $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ - --cov=tutorial -q +The above code renders as follows. As you can see, ``lineno-start`` is not altogether meaningful. -A sidebar, which presents a concept tangentially related to content discussed -on a page, is rendered like so: +.. code-block:: python + :lineno-start: 2 -.. sidebar:: This is a sidebar + if "foo" == "bar": + # This is Python code + pass - Sidebar information. -When multiple objects are imported from the same package, the following -convention is used: +.. _style-guide-includes: - .. code-block:: python +Includes +```````` + +Longer displays of verbatim text may be included by storing the example text in an external file containing only plain text or code. The file may be included using the ``literalinclude`` directive. The file name follows the conventions of :ref:`style-guide-file-conventions`. + +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + +The above code renders as follows. + +.. literalinclude:: narr/helloworld.py + :language: python + +Like code blocks, ``literalinclude`` supports the following options. + +- ``language`` to select a language for syntax highlighting +- ``linenos`` to switch on line numbers +- ``lineno-start`` to specify the starting number to use for line numbering +- ``emphasize-lines`` to emphasize particular lines + +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + :linenos: + :lineno-start: 11 + :emphasize-lines: 1,6-7,9- + +The above code renders as follows. Note that ``lineno-start`` and ``emphasize-lines`` do not align. The former displays numbering starting from the *arbitrarily provided value*, whereas the latter emphasizes the line numbers of the *source file*. - from foo import ( - bar, - baz, - ) +.. literalinclude:: narr/helloworld.py + :language: python + :linenos: + :lineno-start: 11 + :emphasize-lines: 1,6-7,9- -It may look unusual, but it has advantages: +Additional options include the following. -- 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). +.. literalinclude:: narr/helloworld.py + :lines: 1-3 + :emphasize-lines: 3 + :lineno-match: + :language: python -- Looks more neat in cases where a large number of objects get imported from - that package. +.. literalinclude:: narr/helloworld.py + :linenos: + :pyobject: hello_world -- Adding or removing imported objects from the package is quicker and results - in simpler diffs. +.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py + :language: python + :start-after: Start Sphinx Include + :end-before: End Sphinx Include + + +.. _style-guide-inline-code: + +Inline code +``````````` + + + + + + +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` + +References to sections and chapters are presented using the following +style: + + :ref:`traversal_chapter` |