From 7285651ecf3458c61158b8fcf7dbd269f067ffaf Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 21:39:35 -0800 Subject: Add section structure --- docs/style-guide.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 3f2b630d3..49c9d5950 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -47,6 +47,26 @@ Location, referencing, and naming of files will select the image ``pyramid_request_processing.svg`` for the HTML documentation builder, and ``pyramid_request_processing.png`` for the PDF builder. See the related [Stack Overflow post](http://stackoverflow.com/questions/6473660/using-sphinx-docs-how-can-i-specify-png-image-formats-for-html-builds-and-pdf-im/6486713#6486713). +.. _style-guide-section-structure: + +Section structure +----------------- + +Each section, or a subdirectory of reST files, such as a tutorial, must contain an ``index.rst`` file. ``index.rst`` must contain the following. + +- A section heading. This will be visible in the table of contents. +- A single paragraph describing this section. +- A Sphinx ``toctree`` directive, with a ``maxdepth`` of 2. Each ``.rst`` file in the folder should be linked to this ``toctree``. + + .. code-block:: rst + + .. toctree:: + :maxdepth: 2 + + chapter1 + chapter2 + chapter3 + .. _style-guide-page-structure: Page structure -- cgit v1.2.3 From 2954362448347a6a3efd55222a50ece8e2fae6a0 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 21:53:39 -0800 Subject: update headings --- docs/style-guide.rst | 45 ++++++++++++++++++++++++++++++++++++++------- 1 file changed, 38 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 49c9d5950..4a17e1d2b 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -67,6 +67,7 @@ Each section, or a subdirectory of reST files, such as a tutorial, must contain chapter2 chapter3 + .. _style-guide-page-structure: Page structure @@ -104,10 +105,18 @@ Each page should contain in order the following. - Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. +.. _style-guide-page-content: + +Page content +------------ + +Within a page, content should adhere to specific guidelines. + + .. _style-guide-line-lengths: Line lengths ------------- +^^^^^^^^^^^^ Narrative documentation is not code, and should therefore not adhere to PEP8 or other line length conventions. When a translator sees only part of a sentence or paragraph, it makes it more difficult to translate the concept. Line lengths make ``diff`` more difficult. Text editors can soft wrap lines for display to avoid horizontal scrolling. We admit, we boofed it by using arbitrary 79-character line lengths in our own documentation, but we have seen the error of our ways and wish to correct this going forward. @@ -115,7 +124,7 @@ Narrative documentation is not code, and should therefore not adhere to PEP8 or .. _style-guide-trailing-white-space: Trailing white spaces ---------------------- +^^^^^^^^^^^^^^^^^^^^^ - No trailing white spaces. - Always use a line feed or carriage return at the end of a file. @@ -124,7 +133,7 @@ Trailing white spaces .. _style-guide-indentation: Indentation ------------ +^^^^^^^^^^^ - Indent using four spaces. - Do not use tabs to indent. @@ -133,15 +142,37 @@ Indentation .. _style-guide-headings: Headings --------- +^^^^^^^^ + +Capitalize only the first letter in a heading (sentence-case), unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML". + +For consistent heading characters throughout the documentation, follow the guidelines stated in the `Python Developer's Guide `_. Specifically: + +- =, for sections +- -, for subsections +- ^, for subsubsections +- ", for paragraphs + +As individual files do not have so-called "parts" or "chapters", the headings would be underlined with characters as shown. + + .. code-block:: rst + + Heading Level 1 + =============== + + Heading Level 2 + --------------- -Capitalize only the first letter in a heading, unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML". + Heading Level 3 + ^^^^^^^^^^^^^^^ + Heading Level 4 + ``````````````` .. _style-guide-paragraphs: Paragraphs ----------- +^^^^^^^^^^ A paragraph should be on one line. Paragraphs must be separated by two line feeds. @@ -149,7 +180,7 @@ A paragraph should be on one line. Paragraphs must be separated by two line feed .. _style-guide-grammar-spelling-preferences: 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. -- cgit v1.2.3 From c13e6cc241d1f52382435a56a18e791b6b9bbe1a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 21:58:43 -0800 Subject: add links --- docs/style-guide.rst | 42 ++++++++++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 16 deletions(-) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 4a17e1d2b..911949862 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -139,6 +139,27 @@ Indentation - Do not use tabs to indent. +.. _style-guide-grammar-spelling-preferences: + +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 +========== ====================== + + .. _style-guide-headings: Headings @@ -177,25 +198,14 @@ Paragraphs A paragraph should be on one line. Paragraphs must be separated by two line feeds. -.. _style-guide-grammar-spelling-preferences: +Links +^^^^^ -Grammar, spelling, and capitalization preferences -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Use inline links to keep the context or link label together with the URL. Do not use targets and links at the end of the page, because the separation makes it difficult to update and translate. Here is an example of inline links, our required method. -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. + .. code-block:: rst -========== ====================== -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 -========== ====================== + `Example `_ -- cgit v1.2.3 From e33b2ce88af4fb6d9412757ca0ac4f6a95bfc578 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 22:01:15 -0800 Subject: add topic --- docs/style-guide.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 911949862..2304e9d6b 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -198,6 +198,8 @@ Paragraphs A paragraph should be on one line. Paragraphs must be separated by two line feeds. +.. _style-guide-links: + Links ^^^^^ @@ -208,7 +210,22 @@ Use inline links to keep the context or link label together with the URL. Do not `Example `_ +.. _style-guide-topic: + +Topic +^^^^^ + +A topic is similar to a block quote with a title, or a self-contained section with no subsections. Use the ``topic`` directive to indicate a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. Body elements and topics may not contain nested topics. + +The directive's sole argument is interpreted as the topic title, and next line must be blank. All subsequent lines make up the topic body, interpreted as body elements. + + .. code-block:: rst + + .. topic:: Topic Title + Subsequent indented lines comprise + the body of the topic, and are + interpreted as body elements. Literals, filenames, and function arguments are presented using the -- cgit v1.2.3 From ff8acd6f545ca55f9c9588ee77aee559d68ab194 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 22:15:19 -0800 Subject: add syntax highlighting --- docs/style-guide.rst | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) (limited to 'docs') diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 2304e9d6b..cb1a15be1 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -228,6 +228,96 @@ The directive's sole argument is interpreted as the topic title, and next line m interpreted as body elements. +.. _style-guide-syntax-highlighting: + +Syntax highlighting +^^^^^^^^^^^^^^^^^^^ + +Sphinx does syntax highlighting using the `Pygments `_ 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. + + .. code-block:: rst + + .. code-block:: python + + if "foo" == "bar": + # This is Python code + pass + +XML: + + .. code-block:: rst + + .. code-block:: xml + + Some XML + +Unix shell: + + .. code-block:: rst + + .. code-block:: bash + + # Start Plone in foreground mode for a test run + cd ~/Plone/zinstance + bin/plonectl fg + +Windows console: + + .. code-block:: rst + + .. code-block:: doscon + + c:\> %VENV%\Scripts\pcreate -s starter MyProject + +cfg: + + .. code-block:: rst + + .. code-block:: cfg + + [some-part] + # A random part in the buildout + recipe = collective.recipe.foo + option = value + +ini: + + .. code-block:: rst + + .. code-block:: ini + + [nosetests] + match=^test + where=pyramid + nocapture=1 + +Interactive Python: + + .. code-block:: rst + + .. code-block:: pycon + + >>> class Foo: + ... bar = 100 + ... + >>> f = Foo() + >>> f.bar + 100 + >>> f.bar / 0 + Traceback (most recent call last): + File "", line 1, in + ZeroDivisionError: integer division or modulo by zero + +If syntax highlighting is not enabled for your code block, you probably have a syntax error and Pygments will fail silently. + +View the `full list of lexers and associated short names `_. + + + + + Literals, filenames, and function arguments are presented using the following style: -- cgit v1.2.3 From 90db2bc106822be4ba3ca92a51a932f17d5ce4f7 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Nov 2016 02:09:01 -0800 Subject: add code block options - add literal includes - add displaying long commands - add sphinx to intersphinx - garden --- docs/conf.py | 1 + docs/style-guide.rst | 276 +++++++++++++++++++++++++++++++++++---------------- 2 files changed, 194 insertions(+), 83 deletions(-) (limited to 'docs') 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 `_. .. _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 `. + + .. _style-guide-syntax-highlighting: Syntax highlighting -^^^^^^^^^^^^^^^^^^^ +``````````````````` -Sphinx does syntax highlighting using the `Pygments `_ library. +Sphinx does syntax highlighting of code blocks using the `Pygments `_ 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: Some XML -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 `_. +.. _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 `_ + .. 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` -- cgit v1.2.3