From cdee90a86d50667054d140c0a77bbc94a2b788ec Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 22 Nov 2016 05:36:33 -0800 Subject: improve include section - start work on inline and block reST sections --- docs/style-guide.rst | 85 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 65 insertions(+), 20 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 7868f97e7..f665846d2 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -468,7 +468,9 @@ The above code renders as follows. Note that ``lineno-start`` and ``emphasize-li :lineno-start: 11 :emphasize-lines: 1,6-7,9- -``literalinclude`` also supports including only parts of a file. If it is a Python module, you can select a class, function, or method to include using the ``pyobject`` option. +``literalinclude`` also supports including only parts of a file. + +If the source code is a Python module, you can select a class, function, or method to include using the ``pyobject`` option. .. code-block:: rst @@ -482,35 +484,35 @@ The above code renders as follows. It returns the function ``hello_world`` in th :language: python :pyobject: hello_world -Alternatively, you can specify exactly which lines to include by giving a ``lines`` option. +Another way to control which part of the file is included is to use the ``start-after`` and ``end-before`` options (or only one of them). If ``start-after`` is given as a string option, only lines that follow the first line containing that string are included. If ``end-before`` is given as a string option, only lines that precede the first lines containing that string are included. .. code-block:: rst .. literalinclude:: narr/helloworld.py :language: python - :lines: 6-7 + :start-after: from pyramid.response import Response + :end-before: if __name__ == '__main__': The above code renders as follows. .. literalinclude:: narr/helloworld.py :language: python - :lines: 6-7 + :start-after: from pyramid.response import Response + :end-before: if __name__ == '__main__': -Another way to control which part of the file is included is to use the ``start-after`` and ``end-before`` options (or only one of them). If ``start-after`` is given as a string option, only lines that follow the first line containing that string are included. If ``end-before`` is given as a string option, only lines that precede the first lines containing that string are included. +You can specify exactly which lines to include by giving a ``lines`` option. .. code-block:: rst .. literalinclude:: narr/helloworld.py :language: python - :start-after: from pyramid.response import Response - :end-before: if __name__ == '__main__': + :lines: 6-7 The above code renders as follows. .. literalinclude:: narr/helloworld.py :language: python - :start-after: from pyramid.response import Response - :end-before: if __name__ == '__main__': + :lines: 6-7 When specifying particular parts of a file to display, it can be useful to display exactly which lines are being presented. This can be done using the ``lineno-match`` option. @@ -528,42 +530,86 @@ The above code renders as follows. :lines: 6-7 :lineno-match: +.. literalinclude:: narr/helloworld.py + :language: python + :lines: 6-7 + :linenos: + +Out of all the ways to include parts of a file, ``pyobject`` is the most preferred option because if you change your code and add or remove lines, you don't need to adjust line numbering, whereas with ``lines`` you would have to adjust. ``start-after`` and ``end-before`` are less desirable because they depend on source code not changing, or you can insert comments into your source code to act as the delimiters but that just adds comments that have nothing to do with the functionality of your code. + +Above all with includes, if you use line numbering, it's much preferred to use ``lineno-match`` over ``linenos`` with ``lineno-start`` because it "just works" without thinking. + .. _style-guide-inline-code: Inline code ``````````` +Inline code is surrounded by double backtick marks. Literals, filenames, and function arguments are presented using this style. +.. code-block:: rst + Install requirements for building documentation: ``pip install -e ".[docs]"`` +The above code renders as follows. +Install requirements for building documentation: ``pip install -e ".[docs]"`` -Literals, filenames, and function arguments are presented using the -following style: - ``argument1`` +.. _style-guide-block-rest-markup: -Warnings which represent limitations and need-to-know information -related to a topic or concept are presented in the following style: +Block reST markup +----------------- + +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: +Notes which represent additional information related to a topic or concept are presented in the following style: .. note:: This is a note. + + +.. _style-guide-inline-rest-markup: + +Inline reST markup +------------------ + +Italics. + +.. code-block:: rst + + This *word* is italicized. + +The above code renders as follows. + +This *word* is italicized. + +Strong. + +.. code-block:: rst + + This **word** is in bold text. + +The above code renders as follows. + +This **word** is in bold text. + + + + + + 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: +We present Python class names, module names, attributes, and global variables using the following style: :class:`pyramid.config.Configurator.registry` @@ -571,7 +617,6 @@ References to glossary terms are presented using the following style: :term:`Pylons` -References to sections and chapters are presented using the following -style: +References to sections and chapters are presented using the following style: :ref:`traversal_chapter` -- cgit v1.2.3 From a7f3065da246480e674077786d0ab707a9c1c964 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 24 Nov 2016 01:09:16 -0800 Subject: improve links section - add rendering of headings for testing - add topic directive - dedent displaying code - add italics, strong - add Pytyon modules, classes, methods, functions - add tables heading (WIP) - add API documenation (WIP) --- docs/style-guide.rst | 233 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 174 insertions(+), 59 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index f665846d2..45eaed634 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -190,6 +190,20 @@ As individual files do not have so-called "parts" or "chapters", the headings wo Heading Level 4 ``````````````` +The above code renders as follows. + +Heading Level 1 +=============== + +Heading Level 2 +--------------- + +Heading Level 3 +^^^^^^^^^^^^^^^ + +Heading Level 4 +``````````````` + .. _style-guide-paragraphs: Paragraphs @@ -205,9 +219,43 @@ Links 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. - .. code-block:: rst +.. code-block:: rst + + `TryPyramid `_ + +The above code renders as follows. + +`TryPyramid `_ + +To link to pages within this documentation: + +.. code-block:: rst + + :doc:`quick_tour` + +The above code renders as follows. + +:doc:`quick_tour` + +To link to a section within a page in this documentation: + +.. code-block:: rst + + :ref:`quick_tour` + +The above code renders as follows. - `Example `_ +:ref:`quick_tour` + +To link to pages configured via intersphinx: + +.. code-block:: rst + + :ref:`Deform ` + +The above code renders as follows. + +:ref:`Deform ` .. _style-guide-topic: @@ -227,6 +275,13 @@ The directive's sole argument is interpreted as the topic title, and next line m the body of the topic, and are interpreted as body elements. +The above code renders as follows. + +.. topic:: Topic Title + + Subsequent indented lines comprise + the body of the topic, and are + interpreted as body elements. .. _style-guide-displaying-code: @@ -247,78 +302,76 @@ Sphinx does syntax highlighting of code blocks using the `Pygments Some XML + Some XML Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.) - .. code-block:: rst +.. code-block:: rst - .. code-block:: bash + .. code-block:: bash - $ $VENV/bin/pip install -e . + $ $VENV/bin/pip install -e . Windows commands are prefixed with a drive letter with an optional directory name. (See :term:`venv` for the meaning of ``%VENV%``.) - .. code-block:: rst - - .. code-block:: doscon +.. code-block:: rst - c:\> %VENV%\Scripts\pcreate -s starter MyProject + .. code-block:: doscon - .. code-block:: doscon + c:\> %VENV%\Scripts\pcreate -s starter MyProject cfg: - .. code-block:: rst +.. code-block:: rst - .. code-block:: cfg + .. code-block:: cfg - [some-part] - # A random part in the buildout - recipe = collective.recipe.foo - option = value + [some-part] + # A random part in the buildout + recipe = collective.recipe.foo + option = value ini: - .. code-block:: rst +.. code-block:: rst - .. code-block:: ini + .. code-block:: ini - [nosetests] - match=^test - where=pyramid - nocapture=1 + [nosetests] + match=^test + where=pyramid + nocapture=1 Interactive Python: - .. code-block:: rst +.. code-block:: rst - .. code-block:: pycon + .. 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 + >>> 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. @@ -332,12 +385,12 @@ 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: - .. code-block:: rst +.. code-block:: rst - .. code-block:: bash + .. code-block:: bash - $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ - --cov=tutorial -q + $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ + --cov=tutorial -q .. _style-guide-code-block-options: @@ -530,14 +583,9 @@ The above code renders as follows. :lines: 6-7 :lineno-match: -.. literalinclude:: narr/helloworld.py - :language: python - :lines: 6-7 - :linenos: - -Out of all the ways to include parts of a file, ``pyobject`` is the most preferred option because if you change your code and add or remove lines, you don't need to adjust line numbering, whereas with ``lines`` you would have to adjust. ``start-after`` and ``end-before`` are less desirable because they depend on source code not changing, or you can insert comments into your source code to act as the delimiters but that just adds comments that have nothing to do with the functionality of your code. +Out of all the ways to include parts of a file, ``pyobject`` is the most preferred option because if you change your code and add or remove lines, you don't need to adjust line numbering, whereas with ``lines`` you would have to adjust. ``start-after`` and ``end-before`` are less desirable because they depend on source code not changing. Alternatively you can insert comments into your source code to act as the delimiters, but that just adds comments that have nothing to do with the functionality of your code. -Above all with includes, if you use line numbering, it's much preferred to use ``lineno-match`` over ``linenos`` with ``lineno-start`` because it "just works" without thinking. +Above all with includes, if you use line numbering, it's much preferred to use ``lineno-match`` over ``linenos`` with ``lineno-start`` because it "just works" without thinking and with less markup. .. _style-guide-inline-code: @@ -580,7 +628,13 @@ Notes which represent additional information related to a topic or concept are p Inline reST markup ------------------ -Italics. +Within a block of content, inline markup is useful to apply styles and links to other files. + + +.. _style-guide-italics: + +Italics +^^^^^^^ .. code-block:: rst @@ -590,7 +644,11 @@ The above code renders as follows. This *word* is italicized. -Strong. + +.. _style-guide-strong: + +Strong +^^^^^^ .. code-block:: rst @@ -601,17 +659,59 @@ The above code renders as follows. This **word** is in bold text. +.. _style-guide-python: + +Python modules, classes, methods, and functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Python module names use the ``mod`` directive, with the module name as the argument. + +.. code-block:: rst + + :mod:`pyramid.config` + +The above code renders as follows. + +:mod:`pyramid.config` + +Python class names use the ``class`` directive, with the class name as the argument. + +.. code-block:: rst + + :class:`pyramid.config.Configurator` + +The above code renders as follows. + +:class:`pyramid.config.Configurator` + +Python method names use the ``meth`` directive, with the method name as the argument. + +.. code-block:: rst + + :meth:`pyramid.config.Configurator.add_view` + +The above code renders as follows. + +:meth:`pyramid.config.Configurator.add_view` + +Python function names use the ``func`` directive, with the function name as the argument. + +.. code-block:: rst + + :func:`pyramid.renderers.render_to_response` + +The above code renders as follows. +:func:`pyramid.renderers.render_to_response` -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` +:app:`Pyramid` + +:ref:`i18n_chapter` References to glossary terms are presented using the following style: @@ -620,3 +720,18 @@ References to glossary terms are presented using the following style: References to sections and chapters are presented using the following style: :ref:`traversal_chapter` + +.. _style-guide-tables: + +Tables +^^^^^^ + +API documentation +----------------- + +.. automodule:: pyramid.i18n + +.. autoclass:: TranslationString + +.. autofunction:: TranslationStringFactory + -- cgit v1.2.3 From 88dd1fc665b0f2f87e276dde85f4df53d88c6898 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 24 Nov 2016 01:40:58 -0800 Subject: comment out autodoc of TranslationString to get docs to build on Travis-CI https://travis-ci.org/Pylons/pyramid/jobs/178536008#L406 --- docs/api/i18n.rst | 1 + docs/style-guide.rst | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/api/i18n.rst b/docs/api/i18n.rst index 3b9abbc1d..7a61246df 100644 --- a/docs/api/i18n.rst +++ b/docs/api/i18n.rst @@ -6,6 +6,7 @@ .. automodule:: pyramid.i18n .. autoclass:: TranslationString + :noindex: .. autofunction:: TranslationStringFactory diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 45eaed634..641d0fad5 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -731,7 +731,7 @@ API documentation .. automodule:: pyramid.i18n -.. autoclass:: TranslationString +.. .. autoclass:: TranslationString -.. autofunction:: TranslationStringFactory +.. .. autofunction:: TranslationStringFactory -- cgit v1.2.3