Pyramid Starter scaffold

Welcome to \{\{project\}\}, an application generated by
the Pyramid Web Framework {{pyramid_version}}.

Pyramid ZODB scaffold

Welcome to \{\{project\}\}, an application generated by
the Pyramid Web Framework {{pyramid_version}}.

Date: Sat, 22 Oct 2016 15:29:21 -0400 Subject: add jinja2 to manifest --- pyramid/scaffolds/starter/MANIFEST.in_tmpl | 2 +- pyramid/scaffolds/zodb/MANIFEST.in_tmpl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyramid/scaffolds/starter/MANIFEST.in_tmpl b/pyramid/scaffolds/starter/MANIFEST.in_tmpl index 0ff6eb7a0..4d1c86b44 100644 --- a/pyramid/scaffolds/starter/MANIFEST.in_tmpl +++ b/pyramid/scaffolds/starter/MANIFEST.in_tmpl @@ -1,2 +1,2 @@ include *.txt *.ini *.cfg *.rst -recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml +recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml *.jinja2 diff --git a/pyramid/scaffolds/zodb/MANIFEST.in_tmpl b/pyramid/scaffolds/zodb/MANIFEST.in_tmpl index 0ff6eb7a0..4d1c86b44 100644 --- a/pyramid/scaffolds/zodb/MANIFEST.in_tmpl +++ b/pyramid/scaffolds/zodb/MANIFEST.in_tmpl @@ -1,2 +1,2 @@ include *.txt *.ini *.cfg *.rst -recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml +recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml *.jinja2 -- cgit v1.2.3 From e4d66600324ea2d43a36e226933b480e39653bad Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sat, 22 Oct 2016 16:27:11 -0400 Subject: update to match tox.ini --- scaffoldtests.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scaffoldtests.sh b/scaffoldtests.sh index 84fd8e072..1de398991 100755 --- a/scaffoldtests.sh +++ b/scaffoldtests.sh @@ -1,3 +1,3 @@ #!/bin/bash -tox -e{py27,py33,py34,pypy}-scaffolds, +tox -e{py27,py34,py35,pypy}-scaffolds, -- cgit v1.2.3 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 From 8cc4f7891056c085a4060ffe7ec9ce580943133e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 03:33:56 -0800 Subject: Add Introduction - add how to update and contribute - add file conventions - add line conventions --- docs/style-guide.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 856d6ea85..ae56ad9ba 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -1,8 +1,55 @@ -.. _style_guide: +.. _style-guide: Style Guide =========== +This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. + + +.. _style-guide-contribute: + +How to update and contribute to documentation +--------------------------------------------- + +All projects under the Pylons Projects, including this one, follow the guidelines established at `How to Contribute `_ and `Coding Style and Standards `_. + +By building the documentation locally, you can preview the output before committing and pushing your changes to the repository. Follow the instructions for `Building documentation for a Pylons Project project `_. These instructions also include how to install packages required to build the documentation, and how to follow our recommended git workflow. + +When submitting a pull request for the first time in a project, sign `CONTRIBUTORS.txt `_ and commit it along with your pull request. + + +.. _style-guide-file-conventions: + +Location, referencing, and naming of files +------------------------------------------ + +* reStructuredText (reST) files must be located in ``docs/`` and its subdirectories. +* Image files must be located in ``docs/_static/``. +* reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``. +* File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_". +* reST files must have an extension of ``.rst``. +* Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``. For example: + + .. code-block:: rst + + .. image:: ../_static/pyramid_request_processing.* + + 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-lines: + +Line length and paragraphs +-------------------------- + +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. 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. + +A paragraph should be on one line. Paragraphs must be separated by two line feeds. + + + + + Literals, filenames, and function arguments are presented using the following style: -- cgit v1.2.3 From 18a6375cadb8cbf7e44f494c36e0d6c3f696f141 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 05:06:36 -0800 Subject: Add moar sections - trailing white space - indentation - split line lengths and paragraphs --- docs/style-guide.rst | 53 ++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 39 insertions(+), 14 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index ae56ad9ba..5946314e3 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -23,30 +23,55 @@ When submitting a pull request for the first time in a project, sign `CONTRIBUTO Location, referencing, and naming of files ------------------------------------------ -* reStructuredText (reST) files must be located in ``docs/`` and its subdirectories. -* Image files must be located in ``docs/_static/``. -* reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``. -* File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_". -* reST files must have an extension of ``.rst``. -* Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``. For example: +- reStructuredText (reST) files must be located in ``docs/`` and its subdirectories. +- Image files must be located in ``docs/_static/``. +- reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``. +- File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_". +- reST files must have an extension of ``.rst``. +- Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``. For example: .. code-block:: rst - .. image:: ../_static/pyramid_request_processing.* + .. image:: ../_static/pyramid_request_processing.- 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-lines: +.. _style-guide-line-lengths: -Line length and paragraphs --------------------------- +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. 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. +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. + + +.. _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. + + +.. _style-guide-paragraphs: + +Paragraphs +---------- A paragraph should be on one line. Paragraphs must be separated by two line feeds. +.. _style-guide-indentation: + +Indentation +----------- + +- Indent using four spaces. +- Do not use tabs to indent. + + + @@ -145,12 +170,12 @@ 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 +- 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 +- 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 +- Adding or removing imported objects from the package is quicker and results in simpler diffs. -- cgit v1.2.3 From f69e9035d16110d67de5b5a5c0c94bde5bd6b359 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 20 Nov 2016 15:32:42 -0800 Subject: Add Page structure section - add description - add introduction - add headings - add grammar, spelling, capitalization preferences --- docs/style-guide.rst | 87 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 81 insertions(+), 6 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 5946314e3..3f2b630d3 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -3,7 +3,17 @@ Style Guide =========== -This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. +.. admonition:: description + + This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. + + +.. _style-guide-introduction: + +Introduction +------------ + +This chapter provides details of how to contribute updates to the documentation following style guidelines and conventions. We provide examples, including reStructuredText code and its rendered output for both visual and technical reference. .. _style-guide-contribute: @@ -37,6 +47,43 @@ 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-page-structure: + +Page structure +-------------- + +Each page should contain in order the following. + +- The main heading. This will be visible in the table of contents. + + .. code-block:: rst + + ================ + The main heading + ================ + +- The description of the page. This text will be displayed to the reader below the main heading as well as be inserted into the description metadata field of the document. It will be displayed in search engine listings for the page. This is created using the reST ``admonition`` directive. A single paragraph of text consisting of no more than three sentences is recommended, so that the same text fits into search engine results: + + .. code-block:: rst + + .. admonition:: description + + This is a description of the page, which will appear inline and in the description metadata field. + + .. note:: The ``description`` metadata field is not yet implemented in the documentation's Sphinx theme, but it is a `feature request `_, so it is helpful to start using the ``description`` admonition now. + +- Introduction paragraph. + + .. code-block:: rst + + Introduction + ------------ + + This chapter is an introduction. + +- Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. + + .. _style-guide-line-lengths: Line lengths @@ -54,6 +101,23 @@ Trailing white spaces - Always use a line feed or carriage return at the end of a file. +.. _style-guide-indentation: + +Indentation +----------- + +- Indent using four spaces. +- Do not use tabs to indent. + + +.. _style-guide-headings: + +Headings +-------- + +Capitalize only the first letter in a heading, unless other words are proper nouns or acronyms, e.g., "Pyramid" or "HTML". + + .. _style-guide-paragraphs: Paragraphs @@ -62,14 +126,25 @@ Paragraphs A paragraph should be on one line. Paragraphs must be separated by two line feeds. -.. _style-guide-indentation: +.. _style-guide-grammar-spelling-preferences: -Indentation ------------ +Grammar, spelling, and capitalization preferences +------------------------------------------------- -- Indent using four spaces. -- Do not use tabs to indent. +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 +========== ====================== -- cgit v1.2.3 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(+) 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(-) 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(-) 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(+) 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(+) 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 3f130937bcce073e9933e28c332e59c559025e07 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 21 Nov 2016 00:14:26 -0600 Subject: support a [pserve] config section with a list of files to watch fixes #2732 --- docs/narr/project.rst | 20 +++++++++++ pyramid/scripts/pserve.py | 58 ++++++++++++++++++++----------- pyramid/tests/test_scripts/test_pserve.py | 24 ++++++++----- 3 files changed, 73 insertions(+), 29 deletions(-) diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 6c42881f4..b4ad6948e 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1065,3 +1065,23 @@ hard drive, you should install the `watchdog ` package in development. ``hupper`` will automatically use ``watchdog`` to more efficiently poll the filesystem. + +Monitoring Custom Files +~~~~~~~~~~~~~~~~~~~~~~~ + +By default, ``pserve --reload`` will monitor all imported Python code +(everything in ``sys.modules``) as well as the config file passed to +``pserve`` (e.g. ``development.ini``). You can instruct ``pserve`` to watch +other files for changes as well by defining a ``[pserve]`` section in your +configuration file. For example, let's say your application loads the +``favicon.ico`` file at startup and stores it in memory to efficiently +serve it many times. When you change it you want ``pserve`` to restart: + +.. code-block:: ini + + [pserve] + watch_files = + myapp/static/favicon.ico + +Paths are relative to the configuration file and are passed to ``hupper`` +to watch. Currently it does not support globs but this may change. diff --git a/pyramid/scripts/pserve.py b/pyramid/scripts/pserve.py index 969bc07f1..c67dc86ba 100644 --- a/pyramid/scripts/pserve.py +++ b/pyramid/scripts/pserve.py @@ -28,9 +28,11 @@ from paste.deploy.loadwsgi import ( ) from pyramid.compat import PY2 +from pyramid.compat import configparser from pyramid.scripts.common import parse_vars from pyramid.scripts.common import setup_logging +from pyramid.settings import aslist def main(argv=sys.argv, quiet=False): command = PServeCommand(argv, quiet=quiet) @@ -97,12 +99,17 @@ class PServeCommand(object): dest='verbose', help="Suppress verbose output") + ConfigParser = configparser.ConfigParser # testing + loadapp = staticmethod(loadapp) # testing + loadserver = staticmethod(loadserver) # testing + _scheme_re = re.compile(r'^[a-z][a-z]+:', re.I) def __init__(self, argv, quiet=False): self.options, self.args = self.parser.parse_args(argv[1:]) if quiet: self.options.verbose = 0 + self.watch_files = [] def out(self, msg): # pragma: no cover if self.options.verbose > 0: @@ -112,6 +119,24 @@ class PServeCommand(object): restvars = self.args[1:] return parse_vars(restvars) + def pserve_file_config(self, filename): + config = self.ConfigParser() + config.optionxform = str + config.read(filename) + try: + items = dict(config.items('pserve')) + except configparser.NoSectionError: + return + + watch_files = aslist(items.get('watch_files', ''), flatten=False) + + # track file paths relative to the ini file + basedir = os.path.dirname(filename) + for file in watch_files: + if not os.path.isabs(file): + file = os.path.join(basedir, file) + self.watch_files.append(os.path.normpath(file)) + def run(self): # pragma: no cover if not self.args: self.out('You must give a config file') @@ -121,8 +146,12 @@ class PServeCommand(object): vars = self.get_options() app_name = self.options.app_name + base = os.getcwd() if not self._scheme_re.search(app_spec): + config_path = os.path.join(base, app_spec) app_spec = 'config:' + app_spec + else: + config_path = None server_name = self.options.server_name if self.options.server: server_spec = 'egg:pyramid' @@ -130,7 +159,6 @@ class PServeCommand(object): server_name = self.options.server else: server_spec = app_spec - base = os.getcwd() # do not open the browser on each reload so check hupper first if self.options.browser and not hupper.is_active(): @@ -155,22 +183,17 @@ class PServeCommand(object): ) return 0 + if config_path: + setup_logging(config_path, global_conf=vars) + self.watch_files.append(config_path) + self.pserve_file_config(config_path) + if hupper.is_active(): reloader = hupper.get_reloader() - if app_spec.startswith('config:'): - reloader.watch_files([app_spec[len('config:'):]]) - - log_fn = app_spec - if log_fn.startswith('config:'): - log_fn = app_spec[len('config:'):] - elif log_fn.startswith('egg:'): - log_fn = None - if log_fn: - log_fn = os.path.join(base, log_fn) - setup_logging(log_fn, global_conf=vars) + reloader.watch_files(self.watch_files) - server = self.loadserver(server_spec, name=server_name, - relative_to=base, global_conf=vars) + server = self.loadserver( + server_spec, name=server_name, relative_to=base, global_conf=vars) app = self.loadapp( app_spec, name=app_name, relative_to=base, global_conf=vars) @@ -196,13 +219,6 @@ class PServeCommand(object): serve() - def loadapp(self, app_spec, name, relative_to, **kw): # pragma: no cover - return loadapp(app_spec, name=name, relative_to=relative_to, **kw) - - def loadserver(self, server_spec, name, relative_to, **kw):# pragma:no cover - return loadserver( - server_spec, name=name, relative_to=relative_to, **kw) - # For paste.deploy server instantiation (egg:pyramid#wsgiref) def wsgiref_server_runner(wsgi_app, global_conf, **kw): # pragma: no cover from wsgiref.simple_server import make_server diff --git a/pyramid/tests/test_scripts/test_pserve.py b/pyramid/tests/test_scripts/test_pserve.py index e84de92d4..cf9426943 100644 --- a/pyramid/tests/test_scripts/test_pserve.py +++ b/pyramid/tests/test_scripts/test_pserve.py @@ -1,9 +1,12 @@ +import os import unittest +from pyramid.tests.test_scripts import dummy class TestPServeCommand(unittest.TestCase): def setUp(self): from pyramid.compat import NativeIO self.out_ = NativeIO() + self.config_factory = dummy.DummyConfigParserFactory() def out(self, msg): self.out_.write(msg) @@ -11,7 +14,6 @@ class TestPServeCommand(unittest.TestCase): def _get_server(*args, **kwargs): def server(app): return '' - return server def _getTargetClass(self): @@ -23,6 +25,7 @@ class TestPServeCommand(unittest.TestCase): effargs.extend(args) cmd = self._getTargetClass()(effargs) cmd.out = self.out + cmd.ConfigParser = self.config_factory return cmd def test_run_no_args(self): @@ -38,20 +41,15 @@ class TestPServeCommand(unittest.TestCase): self.assertEqual(result, {'a': '1', 'b': '2'}) def test_parse_vars_good(self): - from pyramid.tests.test_scripts.dummy import DummyApp - inst = self._makeOne('development.ini', 'a=1', 'b=2') inst.loadserver = self._get_server - - app = DummyApp() - + app = dummy.DummyApp() def get_app(*args, **kwargs): app.global_conf = kwargs.get('global_conf', None) - inst.loadapp = get_app - inst.run() + inst.run() self.assertEqual(app.global_conf, {'a': '1', 'b': '2'}) def test_parse_vars_bad(self): @@ -59,6 +57,16 @@ class TestPServeCommand(unittest.TestCase): inst.loadserver = self._get_server self.assertRaises(ValueError, inst.run) + def test_config_file_finds_watch_files(self): + inst = self._makeOne('development.ini') + self.config_factory.items = [('watch_files', 'foo\nbar\n/baz')] + inst.pserve_file_config('/base/path.ini') + self.assertEqual(inst.watch_files, [ + os.path.normpath('/base/foo'), + os.path.normpath('/base/bar'), + os.path.normpath('/baz'), + ]) + class Test_main(unittest.TestCase): def _callFUT(self, argv): from pyramid.scripts.pserve import main -- cgit v1.2.3 From abfb2f61458b111008fd1d9de1553380715889a3 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 21 Nov 2016 01:01:47 -0600 Subject: add changelog for #2827 --- CHANGES.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGES.txt b/CHANGES.txt index dac61678d..0686e1ad1 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -116,6 +116,10 @@ Features See https://github.com/Pylons/pyramid/pull/2805 +- A new ``[pserve]`` section is supported in your config files with a + ``watch_files`` key that can configure ``pserve --reload`` to monitor custom + file paths. See https://github.com/Pylons/pyramid/pull/2827 + Bug Fixes --------- -- 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(-) 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 From 60ff6ab9d2c1fcbbe97a39e8e9535d167605d6de Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 21 Nov 2016 04:15:54 -0800 Subject: add literalinclude options --- docs/style-guide.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index c30b199a6..7868f97e7 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -468,22 +468,65 @@ The above code renders as follows. Note that ``lineno-start`` and ``emphasize-li :lineno-start: 11 :emphasize-lines: 1,6-7,9- -Additional options include the following. +``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. + +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + :pyobject: hello_world + +The above code renders as follows. It returns the function ``hello_world`` in the source file. .. literalinclude:: narr/helloworld.py - :lines: 1-3 - :emphasize-lines: 3 - :lineno-match: :language: python + :pyobject: hello_world + +Alternatively, you can specify exactly which lines to include by giving a ``lines`` option. + +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + :lines: 6-7 + +The above code renders as follows. .. literalinclude:: narr/helloworld.py - :linenos: - :pyobject: hello_world + :language: python + :lines: 6-7 + +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. -.. literalinclude:: quick_tour/sqla_demo/sqla_demo/models/mymodel.py +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + :start-after: from pyramid.response import Response + :end-before: if __name__ == '__main__': + +The above code renders as follows. + +.. literalinclude:: narr/helloworld.py + :language: python + :start-after: from pyramid.response import Response + :end-before: if __name__ == '__main__': + +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. + +.. code-block:: rst + + .. literalinclude:: narr/helloworld.py + :language: python + :lines: 6-7 + :lineno-match: + +The above code renders as follows. + +.. literalinclude:: narr/helloworld.py :language: python - :start-after: Start Sphinx Include - :end-before: End Sphinx Include + :lines: 6-7 + :lineno-match: .. _style-guide-inline-code: -- cgit v1.2.3 From 9cab0e7cc24dc95e357db026cead2507111ee93a Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 21 Nov 2016 21:31:41 -0600 Subject: support asset specs in watch_files and variable interpolation --- pyramid/scripts/pserve.py | 46 +++++++++++++++++-------------- pyramid/tests/test_scripts/dummy.py | 8 ++++-- pyramid/tests/test_scripts/test_pserve.py | 19 +++++++++---- 3 files changed, 45 insertions(+), 28 deletions(-) diff --git a/pyramid/scripts/pserve.py b/pyramid/scripts/pserve.py index c67dc86ba..b8776d44f 100644 --- a/pyramid/scripts/pserve.py +++ b/pyramid/scripts/pserve.py @@ -32,6 +32,7 @@ from pyramid.compat import configparser from pyramid.scripts.common import parse_vars from pyramid.scripts.common import setup_logging +from pyramid.path import AssetResolver from pyramid.settings import aslist def main(argv=sys.argv, quiet=False): @@ -119,8 +120,14 @@ class PServeCommand(object): restvars = self.args[1:] return parse_vars(restvars) - def pserve_file_config(self, filename): - config = self.ConfigParser() + def pserve_file_config(self, filename, global_conf=None): + here = os.path.abspath(os.path.dirname(filename)) + defaults = {} + if global_conf: + defaults.update(global_conf) + defaults['here'] = here + + config = self.ConfigParser(defaults=defaults) config.optionxform = str config.read(filename) try: @@ -131,11 +138,13 @@ class PServeCommand(object): watch_files = aslist(items.get('watch_files', ''), flatten=False) # track file paths relative to the ini file - basedir = os.path.dirname(filename) + resolver = AssetResolver(package=None) for file in watch_files: - if not os.path.isabs(file): - file = os.path.join(basedir, file) - self.watch_files.append(os.path.normpath(file)) + if ':' in file: + file = resolver.resolve(file).abspath() + elif not os.path.isabs(file): + file = os.path.join(here, file) + self.watch_files.append(os.path.abspath(file)) def run(self): # pragma: no cover if not self.args: @@ -185,8 +194,8 @@ class PServeCommand(object): if config_path: setup_logging(config_path, global_conf=vars) + self.pserve_file_config(config_path, global_conf=vars) self.watch_files.append(config_path) - self.pserve_file_config(config_path) if hupper.is_active(): reloader = hupper.get_reloader() @@ -205,19 +214,16 @@ class PServeCommand(object): msg = 'Starting server.' self.out(msg) - def serve(): - try: - server(app) - except (SystemExit, KeyboardInterrupt) as e: - if self.options.verbose > 1: - raise - if str(e): - msg = ' ' + str(e) - else: - msg = '' - self.out('Exiting%s (-v to see traceback)' % msg) - - serve() + try: + server(app) + except (SystemExit, KeyboardInterrupt) as e: + if self.options.verbose > 1: + raise + if str(e): + msg = ' ' + str(e) + else: + msg = '' + self.out('Exiting%s (-v to see traceback)' % msg) # For paste.deploy server instantiation (egg:pyramid#wsgiref) def wsgiref_server_runner(wsgi_app, global_conf, **kw): # pragma: no cover diff --git a/pyramid/tests/test_scripts/dummy.py b/pyramid/tests/test_scripts/dummy.py index f3aa20e7c..ced09d0b0 100644 --- a/pyramid/tests/test_scripts/dummy.py +++ b/pyramid/tests/test_scripts/dummy.py @@ -82,8 +82,9 @@ class DummyMultiView(object): self.__request_attrs__ = attrs class DummyConfigParser(object): - def __init__(self, result): + def __init__(self, result, defaults=None): self.result = result + self.defaults = defaults def read(self, filename): self.filename = filename @@ -98,8 +99,9 @@ class DummyConfigParser(object): class DummyConfigParserFactory(object): items = None - def __call__(self): - self.parser = DummyConfigParser(self.items) + def __call__(self, defaults=None): + self.defaults = defaults + self.parser = DummyConfigParser(self.items, defaults) return self.parser class DummyCloser(object): diff --git a/pyramid/tests/test_scripts/test_pserve.py b/pyramid/tests/test_scripts/test_pserve.py index cf9426943..18f7c8c2f 100644 --- a/pyramid/tests/test_scripts/test_pserve.py +++ b/pyramid/tests/test_scripts/test_pserve.py @@ -2,6 +2,8 @@ import os import unittest from pyramid.tests.test_scripts import dummy +here = os.path.abspath(os.path.dirname(__file__)) + class TestPServeCommand(unittest.TestCase): def setUp(self): from pyramid.compat import NativeIO @@ -59,12 +61,19 @@ class TestPServeCommand(unittest.TestCase): def test_config_file_finds_watch_files(self): inst = self._makeOne('development.ini') - self.config_factory.items = [('watch_files', 'foo\nbar\n/baz')] - inst.pserve_file_config('/base/path.ini') + self.config_factory.items = [( + 'watch_files', + 'foo\n/baz\npyramid.tests.test_scripts:*.py', + )] + inst.pserve_file_config('/base/path.ini', global_conf={'a': '1'}) + self.assertEqual(self.config_factory.defaults, { + 'a': '1', + 'here': os.path.abspath('/base'), + }) self.assertEqual(inst.watch_files, [ - os.path.normpath('/base/foo'), - os.path.normpath('/base/bar'), - os.path.normpath('/baz'), + os.path.abspath('/base/foo'), + os.path.abspath('/baz'), + os.path.abspath(os.path.join(here, '*.py')), ]) class Test_main(unittest.TestCase): -- cgit v1.2.3 From ff0da73a8922b5e82c676715078c7b9e60a6a1da Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 21 Nov 2016 22:42:55 -0600 Subject: document globbing --- docs/narr/project.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/narr/project.rst b/docs/narr/project.rst index b4ad6948e..77c637571 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -1083,5 +1083,7 @@ serve it many times. When you change it you want ``pserve`` to restart: watch_files = myapp/static/favicon.ico -Paths are relative to the configuration file and are passed to ``hupper`` -to watch. Currently it does not support globs but this may change. +Paths may be absolute or relative to the configuration file. They may also +be an :term:`asset specification`. These paths are passed to ``hupper`` which +has some basic support for globbing. Acceptable glob patterns depend on the +version of Python being used. -- cgit v1.2.3 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 From bf5c9eaa7e9041fe76cafddf7bad0f397899a6e9 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 14:58:20 -0800 Subject: add todo Sphinx extension for todo blocks - add lists, tables, danger, todo, comments --- docs/conf.py | 8 +- docs/style-guide.rst | 252 +++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 239 insertions(+), 21 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ace921247..0e3f03068 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,9 +51,10 @@ book = os.environ.get('BOOK') extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.doctest', - 'repoze.sphinx.autointerface', - 'sphinx.ext.viewcode', 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.viewcode', + 'repoze.sphinx.autointerface', 'sphinxcontrib.programoutput', # enable pylons_sphinx_latesturl when this branch is no longer "latest" # 'pylons_sphinx_latesturl', @@ -120,6 +121,9 @@ exclude_patterns = ['_themes/README.rst', ] # unit titles (such as .. function::). add_module_names = False +# Add support for todo items +todo_include_todos = True + # The name of the Pygments (syntax highlighting) style to use. #pygments_style = book and 'bw' or 'tango' if book: diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 641d0fad5..73cba0859 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -146,9 +146,9 @@ 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 @@ -157,7 +157,7 @@ plug-in plugin select check, tick (checkbox) such as like verify be sure -========== ====================== +========== ===== .. _style-guide-headings: @@ -604,31 +604,244 @@ The above code renders as follows. Install requirements for building documentation: ``pip install -e ".[docs]"`` -.. _style-guide-block-rest-markup: +.. _style-guide-rest-block-markup: -Block reST markup +reST block markup ----------------- -Warnings which represent limitations and need-to-know information related to a topic or concept are presented in the following style: +This section contains miscellaneous reST block markup for items not already covered. - .. warning:: - This is a warning. +.. _style-guide-lists: -Notes which represent additional information related to a topic or concept are presented in the following style: +Lists +^^^^^ + +Bulleted lists use an asterisk "``*``". + +.. code-block:: rst + + * This is an item in a bulleted list. + * This is another item in a bulleted list. + +The above code renders as follows. + +* This is an item in a bulleted list. +* This is another item in a bulleted list. + +Numbered lists should use a number sign followed by a period "``#.``" and will be numbered automatically. + +.. code-block:: rst + + #. This is an item in a numbered list. + #. This is another item in a numbered list. + +The above code renders as follows. + +#. This is an item in a numbered list. +#. This is another item in a numbered list. + +The appearance of nested lists can be created by separating the child lists from their parent list by blank lines, and indenting by two spaces. Note that Sphinx renders the reST markup not as nested HTML lists, but instead merely indents the children using ``

``. + +.. code-block:: rst + + #. This is a list item in the parent list. + #. This is another list item in the parent list. + + #. This is a list item in the child list. + #. This is another list item in the child list. + + #. This is one more list item in the parent list. + +The above code renders as follows. + +#. This is a list item in the parent list. +#. This is another list item in the parent list. + + #. This is a list item in the child list. + #. This is another list item in the child list. + +#. This is one more list item in the parent list. + + +.. _style-guide-tables: - .. note:: +Tables +^^^^^^ + +Two forms of tables are supported, `simple `_ and `grid `_. + +Simple tables require less markup but have fewer features and some constraints compared to grid tables. The right-most column in simple tables is unbound to the length of the underline in the column header. + +.. code-block:: rst + + ===== ===== + col 1 col 2 + ===== ===== + 1 Second column of row 1. + 2 Second column of row 2. + Second line of paragraph. + 3 - Second column of row 3. + + - Second item in bullet + list (row 3, column 2). + \ Row 4; column 1 will be empty. + ===== ===== + +The above code renders as follows. + +===== ===== +col 1 col 2 +===== ===== +1 Second column of row 1. +2 Second column of row 2. + Second line of paragraph. +3 - Second column of row 3. + + - Second item in bullet + list (row 3, column 2). +\ Row 4; column 1 will be empty. +===== ===== + +Grid tables have much more cumbersome markup, although Emacs' table mode may lessen the tedium. + +.. code-block:: rst + + +------------------------+------------+----------+----------+ + | Header row, column 1 | Header 2 | Header 3 | Header 4 | + | (header rows optional) | | | | + +========================+============+==========+==========+ + | body row 1, column 1 | column 2 | column 3 | column 4 | + +------------------------+------------+----------+----------+ + | body row 2 | Cells may span columns. | + +------------------------+------------+---------------------+ + | body row 3 | Cells may | - Table cells | + +------------------------+ span rows. | - contain | + | body row 4 | | - body elements. | + +------------------------+------------+---------------------+ + +The above code renders as follows. + ++------------------------+------------+----------+----------+ +| Header row, column 1 | Header 2 | Header 3 | Header 4 | +| (header rows optional) | | | | ++========================+============+==========+==========+ +| body row 1, column 1 | column 2 | column 3 | column 4 | ++------------------------+------------+----------+----------+ +| body row 2 | Cells may span columns. | ++------------------------+------------+---------------------+ +| body row 3 | Cells may | - Table cells | ++------------------------+ span rows. | - contain | +| body row 4 | | - body elements. | ++------------------------+------------+---------------------+ + + +.. _style-guide-danger-errors: + +Danger and errors +^^^^^^^^^^^^^^^^^ + +Danger and errors represent critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". ``danger`` and ``error`` appear similarly when rendered, but the HTML generated has the appropriate semantic context. + +.. code-block:: rst + + .. danger:: + + This is danger or an error. + +The above code renders as follows. - This is a note. +.. danger:: + This is danger or an error. +.. todo:: -.. _style-guide-inline-rest-markup: + The style for ``danger`` and ``error`` has not yet been created. -Inline reST markup + +.. _style-guide-warnings: + +Warnings +^^^^^^^^ + +Warnings represent limitations and advice related to a topic or concept. + +.. code-block:: rst + + .. warning:: + + This is a warning. + +The above code renders as follows. + +.. warning:: + + This is a warning. + + +.. _style-guide-notes: + +Notes +^^^^^ + +Notes represent additional information related to a topic or concept. + +.. code-block:: rst + + .. note:: + + This is a note. + +The above code renders as follows. + +.. note:: + + This is a note. + + +.. _style-guide-todo: + +Todo +^^^^ + +Todo items designated tasks that require further work. + +.. code-block:: rst + + .. todo:: + + This is a todo item. + +The above code renders as follows. + +.. todo:: + + This is a todo item. + +.. todo:: + + The todo style is not yet implemented and needs further work. + + +.. _style-guide-comments: + +Comments +^^^^^^^^ + +Comments of the documentation within the documentation may be generated with two periods ``..``. Comments are not rendered, but provide information to documentation authors. + +.. code-block:: rst + + .. This is an example comment. + + +.. _style-guide-rest-inline-markup: + +reST inline markup ------------------ -Within a block of content, inline markup is useful to apply styles and links to other files. +This section contains miscellaneous reST inline markup for items not already covered. Within a block of content, inline markup is useful to apply styles and links to other files. .. _style-guide-italics: @@ -704,8 +917,9 @@ The above code renders as follows. :func:`pyramid.renderers.render_to_response` +.. seealso:: - + See also the Sphinx documentation for the :ref:`reStructuredText Primer `. @@ -717,14 +931,14 @@ References to glossary terms are presented using the following style: :term:`Pylons` +Glossary terms appear in the Glossary + +.. glossary:: :sorted: + References to sections and chapters are presented using the following style: :ref:`traversal_chapter` -.. _style-guide-tables: - -Tables -^^^^^^ API documentation ----------------- -- cgit v1.2.3 From f4518e72c82ad3ef7aeba65ad1221924767b32ea Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 15:45:27 -0800 Subject: replace description with meta - add parsed-literals --- docs/style-guide.rst | 55 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 41 insertions(+), 14 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 73cba0859..f13671704 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -3,9 +3,9 @@ Style Guide =========== -.. admonition:: description - - This chapter describes how to edit, update, and build the :app:`Pyramid` documentation. For coding style guidelines, see `Coding Style `_. +.. meta:: + :description: This chapter describes how to edit, update, and build the Pyramid documentation. + :keywords: Pyramid, Style Guide .. _style-guide-introduction: @@ -15,6 +15,8 @@ Introduction This chapter provides details of how to contribute updates to the documentation following style guidelines and conventions. We provide examples, including reStructuredText code and its rendered output for both visual and technical reference. +For coding style guidelines, see `Coding Style `_. + .. _style-guide-contribute: @@ -75,7 +77,7 @@ Page structure Each page should contain in order the following. -- The main heading. This will be visible in the table of contents. +#. The main heading. This will be visible in the table of contents. .. code-block:: rst @@ -83,17 +85,22 @@ Each page should contain in order the following. The main heading ================ -- The description of the page. This text will be displayed to the reader below the main heading as well as be inserted into the description metadata field of the document. It will be displayed in search engine listings for the page. This is created using the reST ``admonition`` directive. A single paragraph of text consisting of no more than three sentences is recommended, so that the same text fits into search engine results: +#. Meta tag information. The "meta" directive is used to specify HTML metadata stored in HTML META tags. "Metadata" is data about data, in this case data about web pages. Metadata is used to describe and classify web pages in the World Wide Web, in a form that is easy for search engines to extract and collate. .. code-block:: rst - .. admonition:: description + .. meta:: + :description: This chapter describes how to edit, update, and build the Pyramid documentation. + :keywords: Pyramid, Style Guide - This is a description of the page, which will appear inline and in the description metadata field. + The above code renders as follows. - .. note:: The ``description`` metadata field is not yet implemented in the documentation's Sphinx theme, but it is a `feature request `_, so it is helpful to start using the ``description`` admonition now. + .. code-block:: xml -- Introduction paragraph. + + + +#. Introduction paragraph. .. code-block:: rst @@ -102,7 +109,7 @@ Each page should contain in order the following. This chapter is an introduction. -- Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. +#. Finally the content of the document page, consisting of reST elements such as headings, paragraphs, tables, and so on. .. _style-guide-page-content: @@ -378,6 +385,26 @@ 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-parsed-literals: + +Parsed literals +``````````````` + +Parsed literals are used to render, for example, a specific version number of the application in code blocks. Use the directive ``parsed-literal``. Note that syntax highlighting is not supported and code is rendered as plain text. + +.. code-block:: rst + + .. parsed-literal:: + + $ $VENV/bin/pip install "pyramid==\ |release|\ " + +The above code renders as follows. + +.. parsed-literal:: + + $ $VENV/bin/pip install "pyramid==\ |release|\ " + + .. _style-guide-long-commands: Displaying long commands @@ -736,12 +763,12 @@ The above code renders as follows. +------------------------+------------+---------------------+ -.. _style-guide-danger-errors: +.. _style-guide-danger: -Danger and errors -^^^^^^^^^^^^^^^^^ +Danger +^^^^^^ -Danger and errors represent critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". ``danger`` and ``error`` appear similarly when rendered, but the HTML generated has the appropriate semantic context. +Danger represents critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". .. code-block:: rst -- cgit v1.2.3 From 78254d48a39e2b4938297dd568b02ab055b54c3f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 19:20:34 -0800 Subject: add feature versioning, seealso --- docs/style-guide.rst | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index f13671704..51a2efde5 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -763,6 +763,70 @@ The above code renders as follows. +------------------------+------------+---------------------+ +.. _style-guide-feature-versioning: + +Feature versioning +^^^^^^^^^^^^^^^^^^ + +Three directives designate the version in which something is added, changed, or deprecated in the project. + + +.. _style-guide-version-added: + +Version added +````````````` + +To indicate the version in which a feature is added to a project, use the ``versionadded`` directive. If the feature is an entire module, then the directive should be placed at the top of the module section before any prose. + +The first argument is the version. An optional second argument must appear upon a subsequent line, without blank lines in between, and indented. + +.. code-block:: rst + + .. versionadded:: 1.1 + :func:`pyramid.paster.bootstrap` + +The above code renders as follows. + +.. versionadded:: 1.1 + :func:`pyramid.paster.bootstrap` + + +.. _style-guide-version-changed: + +Version changed +``````````````` + +To indicate the version in which a feature is changed in a project, use the ``versionchanged`` directive. Its arguments are the same as ``versionadded``. + +.. code-block:: rst + + .. versionchanged:: 1.8 + Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement. + +The above code renders as follows. + +.. versionchanged:: 1.8 + Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement. + + +.. _style-guide-deprecated: + +Deprecated +`````````` + +Similar to ``versionchanged``, ``deprecated`` describes when the feature was deprecated. An explanation can also be given, for example, to inform the reader what should be used instead. + +.. code-block:: rst + + .. deprecated:: 1.7 + Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised. + +The above code renders as follows. + +.. deprecated:: 1.7 + Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised. + + .. _style-guide-danger: Danger @@ -827,6 +891,26 @@ The above code renders as follows. This is a note. +.. _style-guide-see-also: + +See also +^^^^^^^^ + +"See also" messages refer to topics that are related to the current topic, but have a narrative tone to them instead of merely a link without explanation. "See also" is rendered in a block as well, so that it stands out for the reader's attention. + +.. code-block:: rst + + .. seealso:: + + See :ref:`Quick Tutorial section on Requirements `. + +The above code renders as follows. + +.. seealso:: + + See :ref:`Quick Tutorial section on Requirements `. + + .. _style-guide-todo: Todo -- cgit v1.2.3 From d586ff5c7f22e3bc8e206d865a0760fb28efdb40 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 19:45:42 -0800 Subject: add glossary --- docs/style-guide.rst | 119 +++++++++++++++++++++++++++++++++------------------ 1 file changed, 78 insertions(+), 41 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 51a2efde5..95bfcccfa 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -35,18 +35,60 @@ When submitting a pull request for the first time in a project, sign `CONTRIBUTO Location, referencing, and naming of files ------------------------------------------ -- reStructuredText (reST) files must be located in ``docs/`` and its subdirectories. -- Image files must be located in ``docs/_static/``. -- reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``. -- File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_". -- reST files must have an extension of ``.rst``. -- Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``. For example: +* reStructuredText (reST) files must be located in ``docs/`` and its subdirectories. +* Image files must be located in ``docs/_static/``. +* reST directives must refer to files either relative to the source file or absolute from the top source directory. For example, in ``docs/narr/source.rst``, you could refer to a file in a different directory as either ``.. include:: ../diff-dir/diff-source.rst`` or ``.. include:: /diff-dir/diff-source.rst``. +* File names should be lower-cased and have words separated with either a hyphen "-" or an underscore "_". +* reST files must have an extension of ``.rst``. +* Image files may be any format but must have lower-cased file names and have standard file extensions that consist three letters (``.gif``, ``.jpg``, ``.png``, ``.svg``). ``.gif`` and ``.svg`` are not currently supported by PDF builders in Sphinx, but you can allow the Sphinx builder to automatically select the correct image format for the desired output by replacing the three-letter file extension with ``*``. For example: .. code-block:: rst - .. image:: ../_static/pyramid_request_processing.- + .. image:: ../_static/pyramid_request_processing. - 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). + 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 `_. + + +.. _style-guide-glossary: + +Glossary +-------- + +A glossary defines terms used throughout the documentation. + +The glossary file must be named ``glossary.rst``. Its content must begin with the directive ``glossary``. An optional ``sorted`` argument should be used to sort the terms alphabetically when rendered, making it easier for the user to find a given term. Without the argument ``sorted``, terms will appear in the order of the ``glossary`` source file. + +.. code-block:: rst + + .. glossary:: + :sorted: + + voom + Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it. + + pining + What the Norwegien Blue does when it misses its homeland, e.g., pining for the fjords. + +The above code renders as follows. + +.. glossary:: + :sorted: + + voom + Theoretically, the sound a parrot makes when four-thousand volts of electricity pass through it. + + pining + What the Norwegien Blue does when it misses its homeland, e.g., pining for the fjords. + +References to glossary terms use the ``term`` directive. + +.. code-block:: rst + + :term:`voom` + +The above code renders as follows. Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term. + +:term:`voom` .. _style-guide-section-structure: @@ -56,9 +98,9 @@ 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``. +* 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 @@ -133,8 +175,8 @@ Narrative documentation is not code, and should therefore not adhere to PEP8 or Trailing white spaces ^^^^^^^^^^^^^^^^^^^^^ -- No trailing white spaces. -- Always use a line feed or carriage return at the end of a file. +* No trailing white spaces. +* Always use a line feed or carriage return at the end of a file. .. _style-guide-indentation: @@ -142,8 +184,8 @@ Trailing white spaces Indentation ^^^^^^^^^^^ -- Indent using four spaces. -- Do not use tabs to indent. +* Indent using four spaces. +* Do not use tabs to indent. .. _style-guide-grammar-spelling-preferences: @@ -151,7 +193,7 @@ Indentation 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. +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 @@ -176,10 +218,10 @@ Capitalize only the first letter in a heading (sentence-case), unless other word 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 +* =, 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. @@ -527,10 +569,10 @@ The above code renders as follows. 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 +* ``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 @@ -708,9 +750,9 @@ Simple tables require less markup but have fewer features and some constraints c 1 Second column of row 1. 2 Second column of row 2. Second line of paragraph. - 3 - Second column of row 3. + 3 * Second column of row 3. - - Second item in bullet + * Second item in bullet list (row 3, column 2). \ Row 4; column 1 will be empty. ===== ===== @@ -723,9 +765,9 @@ col 1 col 2 1 Second column of row 1. 2 Second column of row 2. Second line of paragraph. -3 - Second column of row 3. +3 * Second column of row 3. - - Second item in bullet + * Second item in bullet list (row 3, column 2). \ Row 4; column 1 will be empty. ===== ===== @@ -742,9 +784,9 @@ Grid tables have much more cumbersome markup, although Emacs' table mode may les +------------------------+------------+----------+----------+ | body row 2 | Cells may span columns. | +------------------------+------------+---------------------+ - | body row 3 | Cells may | - Table cells | - +------------------------+ span rows. | - contain | - | body row 4 | | - body elements. | + | body row 3 | Cells may | * Table cells | + +------------------------+ span rows. | * contain | + | body row 4 | | * body elements. | +------------------------+------------+---------------------+ The above code renders as follows. @@ -757,9 +799,9 @@ The above code renders as follows. +------------------------+------------+----------+----------+ | body row 2 | Cells may span columns. | +------------------------+------------+---------------------+ -| body row 3 | Cells may | - Table cells | -+------------------------+ span rows. | - contain | -| body row 4 | | - body elements. | +| body row 3 | Cells may | * Table cells | ++------------------------+ span rows. | * contain | +| body row 4 | | * body elements. | +------------------------+------------+---------------------+ @@ -1034,17 +1076,12 @@ The above code renders as follows. -:app:`Pyramid` - -:ref:`i18n_chapter` -References to glossary terms are presented using the following style: - :term:`Pylons` -Glossary terms appear in the Glossary +:app:`Pyramid` -.. glossary:: :sorted: +:ref:`i18n_chapter` References to sections and chapters are presented using the following style: -- cgit v1.2.3 From d1d6a7d9617461ce79bf224ef47aa6af308ff645 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 20:10:00 -0800 Subject: add toctree --- docs/style-guide.rst | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 95bfcccfa..166421eaf 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -49,6 +49,72 @@ 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 `_. +.. _style-guide-table-of-contents-tree: + +Table of contents tree +---------------------- + +To insert a table of contents (TOC), use the ``toctree`` directive. Entries listed under the ``toctree`` directive follow :ref:`location conventions `. A numeric ``maxdepth`` option may be given to indicate the depth of the tree; by default, all levels are included. + +.. code-block:: rst + + .. toctree:: + :maxdepth: 2 + + narr/introduction + narr/install + +The above code renders as follows. + +.. toctree:: + :maxdepth: 2 + + narr/introduction + narr/install + +Globbing can be used. + +.. code-block:: rst + + .. toctree:: + :maxdepth: 1 + :glob: + + pscripts/index + pscripts/* + +The above code renders as follows. + +.. toctree:: + :maxdepth: 1 + :glob: + + pscripts/index + pscripts/* + +To notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive, use the option ``hidden``. This makes sense when you want to insert these links yourself, in a different style, or in the HTML sidebar. + +.. code-block:: rst + + .. toctree:: + :hidden: + + quick_tour + + * :doc:`quick_tour` gives an overview of the major features in Pyramid, covering a little about a lot. + +The above code renders as follows. + +.. toctree:: + :hidden: + + quick_tour + +* :doc:`quick_tour` gives an overview of the major features in Pyramid, covering a little about a lot. + +.. seealso:: Sphinx documentation of :ref:`The TOC tree `. + + .. _style-guide-glossary: Glossary -- cgit v1.2.3 From d7a6a905d55d6c21953812991dafb4163bbf0db1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 21:05:51 -0800 Subject: add cross-referencing --- docs/style-guide.rst | 93 ++++++++++++++++++++++++++++++++-------------------- 1 file changed, 58 insertions(+), 35 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 166421eaf..02f8c18fa 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -112,7 +112,7 @@ The above code renders as follows. * :doc:`quick_tour` gives an overview of the major features in Pyramid, covering a little about a lot. -.. seealso:: Sphinx documentation of :ref:`The TOC tree `. +.. seealso:: Sphinx documentation of :ref:`toctree-directive`. .. _style-guide-glossary: @@ -342,35 +342,7 @@ 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. - -:ref:`quick_tour` - -To link to pages configured via intersphinx: - -.. code-block:: rst - - :ref:`Deform ` - -The above code renders as follows. - -:ref:`Deform ` +.. seealso:: See also :ref:`style-guide-cross-references` for generating links throughout the entire documentation. .. _style-guide-topic: @@ -405,7 +377,7 @@ 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 `. +.. seealso:: See also the Sphinx documentation for :ref:`code-examples`. .. _style-guide-syntax-highlighting: @@ -1138,20 +1110,71 @@ The above code renders as follows. .. seealso:: - See also the Sphinx documentation for the :ref:`reStructuredText Primer `. + See also the Sphinx documentation for the :ref:`rst-primer`. +.. _style-guide-cross-references: +Cross-references +^^^^^^^^^^^^^^^^ +To create cross-references to an arbitrary location, object, document, or other items, use variations of the following syntax. +* ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``. +* ``:role:`~target``` displays the link as only the last component of the target. +* ``:role:`title ``` creates a custom title, instead of the default title of the target. -:app:`Pyramid` + +.. _style-guide-cross-referencing-documents: + +Cross-referencing documents +``````````````````````````` + +To link to pages within this documentation: + +.. code-block:: rst + + :doc:`quick_tour` + +The above code renders as follows. + +:doc:`quick_tour` + + +.. _style-guide-cross-referencing-arbitrary-locations: + +Cross-referencing arbitrary locations +````````````````````````````````````` + +To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. The following section has a label with the syntax ``.. _label_name:`` followed by the section title. + +.. code-block:: rst + + .. _i18n_chapter: + + Internationalization and Localization + ===================================== + +To generate a link to that section with its title, use the following syntax. + +.. code-block:: rst + + :ref:`i18n_chapter` + +The above code renders as follows. :ref:`i18n_chapter` -References to sections and chapters are presented using the following style: +The same syntax works figures and tables with captions. + +For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`Link title ```. + +.. seealso:: See also the Sphinx documentation, :ref:`inline-markup`. + - :ref:`traversal_chapter` + + +:app:`Pyramid` API documentation -- cgit v1.2.3 From d7150db81721df046017632e597193f3250b08e3 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 23:02:18 -0800 Subject: add sphinx extensions --- docs/style-guide.rst | 161 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 121 insertions(+), 40 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 02f8c18fa..0adea0e38 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -1062,11 +1062,74 @@ The above code renders as follows. This **word** is in bold text. +.. seealso:: + + See also the Sphinx documentation for the :ref:`rst-primer`. + + +.. _style-guide-cross-references: + +Cross-references +^^^^^^^^^^^^^^^^ + +To create cross-references to a document, arbitrary location, object, or other items, use variations of the following syntax. + +* ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``. +* ``:role:`~target``` displays the link as only the last component of the target. +* ``:role:`title ``` creates a custom title, instead of the default title of the target. + + +.. _style-guide-cross-referencing-documents: + +Cross-referencing documents +``````````````````````````` + +To link to pages within this documentation: + +.. code-block:: rst + + :doc:`quick_tour` + +The above code renders as follows. -.. _style-guide-python: +:doc:`quick_tour` + + +.. _style-guide-cross-referencing-arbitrary-locations: + +Cross-referencing arbitrary locations +````````````````````````````````````` + +To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. The following section has a label with the syntax ``.. _label_name:`` followed by the section title. + +.. code-block:: rst + + .. _i18n_chapter: + + Internationalization and Localization + ===================================== + +To generate a link to that section with its title, use the following syntax. + +.. code-block:: rst + + :ref:`i18n_chapter` + +The above code renders as follows. + +:ref:`i18n_chapter` + +The same syntax works figures and tables with captions. + +For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`Link title ```. + +.. seealso:: See also the Sphinx documentation, :ref:`inline-markup`. + + +.. _style-guide-cross-referencing-python: Python modules, classes, methods, and functions -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +``````````````````````````````````````````````` Python module names use the ``mod`` directive, with the module name as the argument. @@ -1108,81 +1171,99 @@ The above code renders as follows. :func:`pyramid.renderers.render_to_response` -.. seealso:: - - See also the Sphinx documentation for the :ref:`rst-primer`. +Note that you can use either or combine the ``~`` and ``.`` prefixes. However, we prefer not to use the ``.`` prefix because Sphinx might generate an error if it cannot disambiguate the reference. +.. code-block:: rst -.. _style-guide-cross-references: + :func:`~.render_to_response` -Cross-references -^^^^^^^^^^^^^^^^ +The above code renders as follows. -To create cross-references to an arbitrary location, object, document, or other items, use variations of the following syntax. +:func:`~.render_to_response` -* ``:role:`target``` creates a link to the item named ``target`` of the type indicated by ``role``, with the link's text as the title of the target. ``target`` may need to be disambiguated between documentation sets linked through intersphinx, in which case the syntax would be ``deform:overview``. -* ``:role:`~target``` displays the link as only the last component of the target. -* ``:role:`title ``` creates a custom title, instead of the default title of the target. +.. _style-guide-role-app-pyramid: -.. _style-guide-cross-referencing-documents: +The role ``:app:`Pyramid``` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Cross-referencing documents -``````````````````````````` +We use the special role ``app`` to refer to the application "Pyramid". -To link to pages within this documentation: .. code-block:: rst - :doc:`quick_tour` + :app:`Pyramid` The above code renders as follows. -:doc:`quick_tour` +:app:`Pyramid` -.. _style-guide-cross-referencing-arbitrary-locations: +.. _style-guide-sphinx-extensions: -Cross-referencing arbitrary locations -````````````````````````````````````` +Sphinx extensions +----------------- -To support cross-referencing to arbitrary locations in any document and between documentation sets via intersphinx, the standard reST labels are used. For this to work, label names must be unique throughout the entire documentation including externally linked intersphinx references. There are two ways in which you can refer to labels, if they are placed directly before a section title, a figure, or table with a caption, or at any other location. The following section has a label with the syntax ``.. _label_name:`` followed by the section title. +We use several Sphinx extensions to add features to our documentation. Extensions need to be enabled and configured in ``docs/conf.py`` before they can be used. -.. code-block:: rst - .. _i18n_chapter: +.. _style-guide-sphinx-extension-autodoc: - Internationalization and Localization - ===================================== +:mod:`sphinx.ext.autodoc` +------------------------- -To generate a link to that section with its title, use the following syntax. +API documentation uses the Sphinx extension :mod:`sphinx.ext.autodoc` to include documentation from docstrings. -.. code-block:: rst +See the source of any documentation within the ``docs/api/`` directory for conventions and usage, as well as the Sphinx extension's :mod:`documentation `. - :ref:`i18n_chapter` -The above code renders as follows. +.. _style-guide-sphinx-extension-doctest: -:ref:`i18n_chapter` +:mod:`sphinx.ext.doctest` +------------------------- -The same syntax works figures and tables with captions. +:mod:`sphinx.ext.doctest` allows you to test code snippets in the documentation in a natural way. It works by collecting specially-marked up code blocks and running them as doctest tests. We have only a few tests in our Pyramid documentation which can be found in ``narr/sessions.rst`` and ``narr/hooks.rst``. -For labels that are not placed as mentioned, the link must be given an explicit title, such as ``:ref:`Link title ```. -.. seealso:: See also the Sphinx documentation, :ref:`inline-markup`. +.. _style-guide-sphinx-extension-intersphinx: +:mod:`sphinx.ext.intersphinx` +----------------------------- +:mod:`sphinx.ext.intersphinx` generates links to the documentation of objects in other projects. -:app:`Pyramid` +.. _style-guide-sphinx-extension-todo: +:mod:`sphinx.ext.todo` +---------------------- + +:mod:`sphinx.ext.todo` adds support for todo items. + + +.. _style-guide-sphinx-extension-viewcode: + +:mod:`sphinx.ext.viewcode` +-------------------------- + +:mod:`sphinx.ext.viewcode` looks at your Python object descriptions and tries to find the source files where the objects are contained. When found, a separate HTML page will be output for each module with a highlighted version of the source code, and a link will be added to all object descriptions that leads to the source code of the described object. A link back from the source to the description will also be inserted. -API documentation ------------------ -.. automodule:: pyramid.i18n +.. _style-guide-sphinx-extension-repoze-sphinx-autointerface: -.. .. autoclass:: TranslationString +`repoze.sphinx.autointerface `_ +----------------------------------------------------------------------------------------- -.. .. autofunction:: TranslationStringFactory +`repoze.sphinx.autointerface `_ auto-generates API docs from Zope interfaces. + + +.. _style-guide-script-documentation: + +Script documentation +-------------------- + +We currently use `sphinxcontrib-programoutput `_ to generate program output of the p* scripts. It is no longer maintained and may cause future builds of the documentation to fail. + +.. todo:: + See `issue #2804 `_ for further discussion. -- cgit v1.2.3 From 0eb59ec16a05171e0a6e5e4649b7c03448413d76 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 25 Nov 2016 23:43:25 -0800 Subject: eat dog food: use " not ` for headings --- docs/style-guide.rst | 31 +++++++++++++++---------------- 1 file changed, 15 insertions(+), 16 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 0adea0e38..ca6d7279b 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -259,7 +259,7 @@ Indentation 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. +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 @@ -303,7 +303,7 @@ As individual files do not have so-called "parts" or "chapters", the headings wo ^^^^^^^^^^^^^^^ Heading Level 4 - ``````````````` + """"""""""""""" The above code renders as follows. @@ -317,7 +317,7 @@ Heading Level 3 ^^^^^^^^^^^^^^^ Heading Level 4 -``````````````` +""""""""""""""" .. _style-guide-paragraphs: @@ -383,7 +383,7 @@ Code may be displayed in blocks or inline. You can include blocks of code from o .. _style-guide-syntax-highlighting: Syntax highlighting -``````````````````` +""""""""""""""""""" Sphinx does syntax highlighting of code blocks using the `Pygments `_ library. @@ -468,7 +468,7 @@ View the `full list of lexers and associated short names Date: Sat, 26 Nov 2016 00:06:41 -0800 Subject: minor gardening --- docs/style-guide.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/style-guide.rst b/docs/style-guide.rst index ca6d7279b..70f899651 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -250,7 +250,7 @@ Trailing white spaces Indentation ^^^^^^^^^^^ -* Indent using four spaces. +* Indent using four spaces, except for :ref:`nested lists `. * Do not use tabs to indent. @@ -387,7 +387,7 @@ Syntax highlighting 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. +Do not use two colons "::" at the end of a line, followed by a blank line, then code. Always specify the language to be used for syntax highlighting by using a language argument in the ``code-block`` directive. Always indent the subsequent code. .. code-block:: rst @@ -449,16 +449,16 @@ Interactive Python: .. 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. @@ -545,7 +545,7 @@ The above code renders as follows. # This is Python code 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``. +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`` (see :ref:`style-guide-cross-referencing-arbitrary-locations`). .. code-block:: rst @@ -578,7 +578,7 @@ To specify the starting number to use for line numbering, use the ``lineno-start # This is Python code pass -The above code renders as follows. As you can see, ``lineno-start`` is not altogether meaningful. +The above code renders as follows. As you can see, ``lineno-start`` is not altogether accurate. .. code-block:: python :lineno-start: 2 @@ -1171,15 +1171,15 @@ The above code renders as follows. :func:`pyramid.renderers.render_to_response` -Note that you can use either or combine the ``~`` and ``.`` prefixes. However, we prefer not to use the ``.`` prefix because Sphinx might generate an error if it cannot disambiguate the reference. +Note that you can use the ``~`` prefix to show only the last segment of a Python object's name. We prefer not to use the ``.`` prefix, even though it may seem to be a convenience to documentation authors, because Sphinx might generate an error if it cannot disambiguate the reference. .. code-block:: rst - :func:`~.render_to_response` + :func:`~pyramid.renderers.render_to_response` The above code renders as follows. -:func:`~.render_to_response` +:func:`~pyramid.renderers.render_to_response` .. _style-guide-role-app-pyramid: -- cgit v1.2.3 From 5f5e757dadae19a0c69069733a139eaf217f3ddd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sat, 26 Nov 2016 00:10:34 -0800 Subject: add change note --- CHANGES.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES.txt b/CHANGES.txt index 1939ad125..59f77368f 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -115,6 +115,9 @@ Deprecations Documentation Changes --------------------- +- Replace Typographical Conventions with an enhanced Style Guide. + https://github.com/Pylons/pyramid/pull/2838 + - Add pyramid_nacl_session to session factories. See https://github.com/Pylons/pyramid/issues/2791 -- cgit v1.2.3 From b99ada66150f9155ed959338f2053e544a6c8265 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 28 Nov 2016 23:14:16 -0800 Subject: restore Typographical Conventions, an edited and condensed version of the Style Guide --- docs/index.rst | 5 +- docs/style-guide.rst | 34 ++- docs/typographical-conventions.rst | 427 +++++++++++++++++++++++++++++++++++++ 3 files changed, 442 insertions(+), 24 deletions(-) create mode 100644 docs/typographical-conventions.rst diff --git a/docs/index.rst b/docs/index.rst index f41154c19..a783e8a70 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -213,12 +213,13 @@ Copyright, Trademarks, and Attributions copyright -Style Guide -=========== +Typographical Conventions and Style Guide +========================================= .. toctree:: :maxdepth: 1 + typographical-conventions style-guide diff --git a/docs/style-guide.rst b/docs/style-guide.rst index 70f899651..bdca45a06 100644 --- a/docs/style-guide.rst +++ b/docs/style-guide.rst @@ -293,31 +293,21 @@ As individual files do not have so-called "parts" or "chapters", the headings wo .. code-block:: rst - Heading Level 1 - =============== + ================================== + The main heading or web page title + ================================== - Heading Level 2 + Heading Level 1 --------------- - Heading Level 3 + Heading Level 2 ^^^^^^^^^^^^^^^ - Heading Level 4 + Heading Level 3 """"""""""""""" -The above code renders as follows. - -Heading Level 1 -=============== - -Heading Level 2 ---------------- +Note, we do not render heading levels here because doing so causes a loss in page structure. -Heading Level 3 -^^^^^^^^^^^^^^^ - -Heading Level 4 -""""""""""""""" .. _style-guide-paragraphs: @@ -375,7 +365,7 @@ The above code renders as follows. 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. +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, and may use line numbering or emphasis. .. seealso:: See also the Sphinx documentation for :ref:`code-examples`. @@ -427,10 +417,10 @@ 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: diff --git a/docs/typographical-conventions.rst b/docs/typographical-conventions.rst new file mode 100644 index 000000000..cd4de8800 --- /dev/null +++ b/docs/typographical-conventions.rst @@ -0,0 +1,427 @@ +.. _typographical-conventions: + +Typographical Conventions +========================= + +.. meta:: + :description: This chapter describes typographical conventions used in the Pyramid documentation. + :keywords: Pyramid, Typographical Conventions + + +.. _typographical-conventions-introduction: + +Introduction +------------ + +This chapter describes typographical conventions used in the Pyramid documentation. Documentation authors and contributors should review the :ref:`style-guide`. + + +.. _typographical-conventions-glossary: + +Glossary +-------- + +A glossary defines terms used throughout the documentation. References to glossary terms appear as follows. + +:term:`request` + +Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term. + + +.. _typographical-conventions-headings: + +Headings +-------- + +Sections, sub-sections, and sub-sub-sections within a web page or chapter are denoted with headings at various levels. The immediately preceding heading "Headings" is a section heading. Sub-section and sub-sub-section headings are shown as follows. + +Heading Level 2 +^^^^^^^^^^^^^^^ + +sub-section + +Heading Level 3 +""""""""""""""" + +sub-sub-section + + +.. _typographical-conventions-paragraphs: + +Paragraphs +---------- + +A paragraph of text looks exactly like this paragraph. + + +.. _typographical-conventions-links: + +Links +----- + +Links are presented as follows, and may be clickable. + +`TryPyramid `_ + +.. seealso:: See also :ref:`typographical-conventions-cross-references` for other links within the documentation. + + +.. _typographical-conventions-topic: + +Topic +----- + +A topic is similar to a block quote with a title, or a self-contained section with no subsections. A topic indicates a self-contained idea that is separate from the flow of the document. Topics may occur anywhere a section or transition may occur. + +.. topic:: Topic Title + + Subsequent indented lines comprise + the body of the topic, and are + interpreted as body elements. + + +.. _typographical-conventions-displaying-code: + +Code +---- + +Code may be displayed in blocks or inline. Blocks of code may use syntax highlighting, line numbering, and emphasis. + + +.. _typographical-conventions-syntax-highlighting: + +Syntax highlighting +^^^^^^^^^^^^^^^^^^^ + +XML: + +.. code-block:: xml + + Some XML + +Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.) + +.. code-block:: bash + + $ $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:: doscon + + c:\> %VENV%\Scripts\pcreate -s starter MyProject + +cfg: + +.. code-block:: cfg + + [some-part] + # A random part in the buildout + recipe = collective.recipe.foo + option = value + +ini: + +.. code-block:: ini + + [nosetests] + match=^test + where=pyramid + nocapture=1 + +Interactive Python: + +.. 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 + + +.. _typographical-conventions-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: + +.. code-block:: bash + + $ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ + --cov=tutorial -q + + +.. _typographical-conventions-code-block-options: + +Code block options +^^^^^^^^^^^^^^^^^^ + +To emphasize lines, we give the appearance that a highlighting pen has been used on the code. + +.. code-block:: python + :emphasize-lines: 1,3 + + if "foo" == "bar": + # This is Python code + pass + +A code block with line numbers. + +.. code-block:: python + :linenos: + + if "foo" == "bar": + # This is Python code + pass + +Some code blocks may be given a caption. + +.. code-block:: python + :caption: sample.py + :name: sample-py + + if "foo" == "bar": + # This is Python code + pass + + +.. _typographical-conventions-inline-code: + +Inline code +^^^^^^^^^^^ + +Inline code is displayed as follows, where the inline code is 'pip install -e ".[docs]"'. + +Install requirements for building documentation: ``pip install -e ".[docs]"`` + + +.. _typographical-conventions-lists: + +Lists +----- + +Bulleted lists display as follows. + +* This is an item in a bulleted list. +* This is another item in a bulleted list. + +Numbered lists display as follows. + +#. This is an item in a numbered list. +#. This is another item in a numbered list. + +Nested lists display as follows. + +#. This is a list item in the parent list. +#. This is another list item in the parent list. + + #. This is a list item in the child list. + #. This is another list item in the child list. + +#. This is one more list item in the parent list. + + +.. _typographical-conventions-tables: + +Tables +------ + +Tables display as follows. + +===== ===== +col 1 col 2 +===== ===== +1 Second column of row 1. +2 Second column of row 2. + Second line of paragraph. +3 * Second column of row 3. + + * Second item in bullet + list (row 3, column 2). +\ Row 4; column 1 will be empty. +===== ===== + + +.. _typographical-conventions-feature-versioning: + +Feature versioning +------------------ + +We designate the version in which something is added, changed, or deprecated in the project. + + +.. _typographical-conventions-version-added: + +Version added +^^^^^^^^^^^^^ + +The version in which a feature is added to a project is displayed as follows. + +.. versionadded:: 1.1 + :func:`pyramid.paster.bootstrap` + + +.. _typographical-conventions-version-changed: + +Version changed +^^^^^^^^^^^^^^^ + +The version in which a feature is changed in a project is displayed as follows. + +.. versionchanged:: 1.8 + Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement. + + +.. _typographical-conventions-deprecated: + +Deprecated +^^^^^^^^^^ + +The version in which a feature is deprecated in a project is displayed as follows. + +.. deprecated:: 1.7 + Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised. + + +.. _typographical-conventions-danger: + +Danger +------ + +Danger represents critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". + +.. danger:: + + This is danger or an error. + + +.. _typographical-conventions-warnings: + +Warnings +-------- + +Warnings represent limitations and advice related to a topic or concept. + +.. warning:: + + This is a warning. + + +.. _typographical-conventions-notes: + +Notes +----- + +Notes represent additional information related to a topic or concept. + +.. note:: + + This is a note. + + +.. _typographical-conventions-see-also: + +See also +-------- + +"See also" messages refer to topics that are related to the current topic, but have a narrative tone to them instead of merely a link without explanation. "See also" is rendered in a block as well, so that it stands out for the reader's attention. + +.. seealso:: + + See :ref:`Quick Tutorial section on Requirements `. + + +.. _typographical-conventions-todo: + +Todo +---- + +Todo items designated tasks that require further work. + +.. todo:: + + This is a todo item. + + +.. _typographical-conventions-italics: + +Italics +------- + +This *word* is italicized. + + +.. _typographical-conventions-strong: + +Strong +------ + +This **word** is in bold text. + + +.. _typographical-conventions-cross-references: + +Cross-references +---------------- + +Cross-references are links that may be to a document, arbitrary location, object, or other items. + + +.. _typographical-conventions-cross-referencing-documents: + +Cross-referencing documents +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Links to pages within this documentation display as follows. + +:doc:`quick_tour` + + +.. _typographical-conventions-cross-referencing-arbitrary-locations: + +Cross-referencing arbitrary locations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Links to sections, and tables and figures with captions, within this documentation display as follows. + +:ref:`i18n_chapter` + + +.. _typographical-conventions-cross-referencing-python: + +Python modules, classes, methods, and functions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All of the following are clickable links to Python modules, classes, methods, and functions. + +Python module names display as follows. + +:mod:`pyramid.config` + +Python class names display as follows. + +:class:`pyramid.config.Configurator` + +Python method names display as follows. + +:meth:`pyramid.config.Configurator.add_view` + +Python function names display as follows. + +:func:`pyramid.renderers.render_to_response` + +Sometimes we show only the last segment of a Python object's name, which displays as follows. + +:func:`~pyramid.renderers.render_to_response` + +The application "Pyramid" itself displays as follows. + +:app:`Pyramid` + -- cgit v1.2.3 From fa842555b41f807c8f4a8528113d7742eb7633e8 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Mon, 28 Nov 2016 23:21:18 -0800 Subject: fix warning about duplicate name --- docs/typographical-conventions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/typographical-conventions.rst b/docs/typographical-conventions.rst index cd4de8800..5c7efea31 100644 --- a/docs/typographical-conventions.rst +++ b/docs/typographical-conventions.rst @@ -185,7 +185,7 @@ Some code blocks may be given a caption. .. code-block:: python :caption: sample.py - :name: sample-py + :name: sample-py-typographical-conventions if "foo" == "bar": # This is Python code -- cgit v1.2.3 From b01a0233aa03b4b5a9ddd640a7a114f68d1c763d Mon Sep 17 00:00:00 2001 From: Martin Date: Tue, 6 Dec 2016 16:36:56 +0100 Subject: Changed wiki tutorial to showcase passwrd hashing with bcrypt. Relates to #2204 --- docs/tutorials/wiki/authorization.rst | 35 +++++++++++++++++++++- docs/tutorials/wiki/definingviews.rst | 1 + docs/tutorials/wiki/src/authorization/setup.py | 1 + .../wiki/src/authorization/tutorial/security.py | 15 ++++++++-- .../wiki/src/authorization/tutorial/views.py | 4 +-- docs/tutorials/wiki/src/tests/setup.py | 1 + docs/tutorials/wiki/src/tests/tutorial/security.py | 15 ++++++++-- docs/tutorials/wiki/src/tests/tutorial/tests.py | 11 +++++++ docs/tutorials/wiki/src/tests/tutorial/views.py | 4 +-- 9 files changed, 78 insertions(+), 9 deletions(-) diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index 44097b35b..699e34355 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -18,6 +18,7 @@ require permission, instead of a default "403 Forbidden" page. We will implement the access control with the following steps: +* Add password hashing dependencies * Add users and groups (``security.py``, a new module). * Add an :term:`ACL` (``models.py``). * Add an :term:`authentication policy` and an :term:`authorization policy` @@ -38,6 +39,25 @@ Then we will add the login and logout feature: Access control -------------- +Add dependencies +~~~~~~~~~~~~~~~~ + +Just like in :ref:`wiki_defining_views` we need a new dependency. +We need to add the ``bcrypt`` package, to our tutorial package's +``setup.py`` file by assigning this dependency to the ``requires`` parameter +in the ``setup()`` function. + +Open ``setup.py`` and edit it to look like the following: + +.. literalinclude:: src/authorization/setup.py + :linenos: + :emphasize-lines: 21 + :language: python + +Only the highlighted line needs to be added. + +Do not forget to run ``pip install -e .`` just like in :ref:`wiki-running-pip-install`. + Add users and groups ~~~~~~~~~~~~~~~~~~~~ @@ -61,7 +81,20 @@ request)`` returns ``None``. We will use ``groupfinder()`` as an :term:`authentication policy` "callback" that will provide the :term:`principal` or principals for a user. -In a production system, user and group data will most often come from a +There are two helper methods that will help us later when loging-in users. +The first is ``hash_password`` which takes a raw password and transforms it using +bcrypt into an irreversible representation, a process known as "hashing". The +second method, ``check_password``, will allow us to compare the hashed value of the +submitted password against the hashed value of the password stored in the user's +record. If the two hashed values match, then the submitted +password is valid, and we can authenticate the user. + +We hash passwords so that it is impossible to decrypt them and use them to +authenticate in the application. If we stored passwords foolishly in clear text, +then anyone with access to the database could retrieve any password to authenticate +as any user. + +In a production system, user and group data will most often be saved and come from a database, but here we use "dummy" data to represent user and groups sources. Add an ACL diff --git a/docs/tutorials/wiki/definingviews.rst b/docs/tutorials/wiki/definingviews.rst index ac94d8059..3859d2cad 100644 --- a/docs/tutorials/wiki/definingviews.rst +++ b/docs/tutorials/wiki/definingviews.rst @@ -52,6 +52,7 @@ Open ``setup.py`` and edit it to look like the following: Only the highlighted line needs to be added. +.. _wiki-running-pip-install: Running ``pip install -e .`` ============================ diff --git a/docs/tutorials/wiki/src/authorization/setup.py b/docs/tutorials/wiki/src/authorization/setup.py index beeed75c9..68e3c0abd 100644 --- a/docs/tutorials/wiki/src/authorization/setup.py +++ b/docs/tutorials/wiki/src/authorization/setup.py @@ -18,6 +18,7 @@ requires = [ 'ZODB3', 'waitress', 'docutils', + 'bcrypt', ] tests_require = [ diff --git a/docs/tutorials/wiki/src/authorization/tutorial/security.py b/docs/tutorials/wiki/src/authorization/tutorial/security.py index d88c9c71f..4115c780c 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/security.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/security.py @@ -1,5 +1,16 @@ -USERS = {'editor':'editor', - 'viewer':'viewer'} +import bcrypt + + +def hash_password(pw): + return bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + +def check_password(expected_hash, pw): + if expected_hash is not None: + return bcrypt.checkpw(pw.encode('utf-8'), expected_hash) + return False + +USERS = {'editor': hash_password('editor'), + 'viewer': hash_password('viewer')} GROUPS = {'editor':['group:editors']} def groupfinder(userid, request): diff --git a/docs/tutorials/wiki/src/authorization/tutorial/views.py b/docs/tutorials/wiki/src/authorization/tutorial/views.py index c271d2cc1..e4560dfe1 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/views.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/views.py @@ -14,7 +14,7 @@ from pyramid.security import ( ) -from .security import USERS +from .security import USERS, check_password from .models import Page # regular expression used to find WikiWords @@ -94,7 +94,7 @@ def login(request): if 'form.submitted' in request.params: login = request.params['login'] password = request.params['password'] - if USERS.get(login) == password: + if check_password(USERS.get(login), password): headers = remember(request, login) return HTTPFound(location=came_from, headers=headers) diff --git a/docs/tutorials/wiki/src/tests/setup.py b/docs/tutorials/wiki/src/tests/setup.py index beeed75c9..68e3c0abd 100644 --- a/docs/tutorials/wiki/src/tests/setup.py +++ b/docs/tutorials/wiki/src/tests/setup.py @@ -18,6 +18,7 @@ requires = [ 'ZODB3', 'waitress', 'docutils', + 'bcrypt', ] tests_require = [ diff --git a/docs/tutorials/wiki/src/tests/tutorial/security.py b/docs/tutorials/wiki/src/tests/tutorial/security.py index d88c9c71f..4115c780c 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/security.py +++ b/docs/tutorials/wiki/src/tests/tutorial/security.py @@ -1,5 +1,16 @@ -USERS = {'editor':'editor', - 'viewer':'viewer'} +import bcrypt + + +def hash_password(pw): + return bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + +def check_password(expected_hash, pw): + if expected_hash is not None: + return bcrypt.checkpw(pw.encode('utf-8'), expected_hash) + return False + +USERS = {'editor': hash_password('editor'), + 'viewer': hash_password('viewer')} GROUPS = {'editor':['group:editors']} def groupfinder(userid, request): diff --git a/docs/tutorials/wiki/src/tests/tutorial/tests.py b/docs/tutorials/wiki/src/tests/tutorial/tests.py index 04beaea44..098e9c1bd 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/tests.py +++ b/docs/tutorials/wiki/src/tests/tutorial/tests.py @@ -122,6 +122,17 @@ class EditPageTests(unittest.TestCase): self.assertEqual(response.location, 'http://example.com/') self.assertEqual(context.data, 'Hello yo!') +class SecurityTests(unittest.TestCase): + def test_hashing(self): + from .security import hash_password, check_password + password = 'secretpassword' + hashed_password = hash_password(password) + self.assertTrue(check_password(hashed_password, password)) + + self.assertFalse(check_password(hashed_password, 'attackerpassword')) + + self.assertFalse(check_password(None, password)) + class FunctionalTests(unittest.TestCase): viewer_login = '/login?login=viewer&password=viewer' \ diff --git a/docs/tutorials/wiki/src/tests/tutorial/views.py b/docs/tutorials/wiki/src/tests/tutorial/views.py index c271d2cc1..e4560dfe1 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/views.py +++ b/docs/tutorials/wiki/src/tests/tutorial/views.py @@ -14,7 +14,7 @@ from pyramid.security import ( ) -from .security import USERS +from .security import USERS, check_password from .models import Page # regular expression used to find WikiWords @@ -94,7 +94,7 @@ def login(request): if 'form.submitted' in request.params: login = request.params['login'] password = request.params['password'] - if USERS.get(login) == password: + if check_password(USERS.get(login), password): headers = remember(request, login) return HTTPFound(location=came_from, headers=headers) -- cgit v1.2.3 From b4abcd1f596297eb083e855d5e9a158d9e108c81 Mon Sep 17 00:00:00 2001 From: Martin Date: Wed, 7 Dec 2016 09:43:22 +0100 Subject: Hashing helpers now deal in unicode. Fixed wording. Added link to bcrypt and a footnote from wiki2 example. --- docs/tutorials/wiki/authorization.rst | 16 ++++++++++++---- .../wiki/src/authorization/tutorial/security.py | 6 ++++-- docs/tutorials/wiki/src/tests/tutorial/security.py | 6 ++++-- 3 files changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index 699e34355..523acc53b 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -43,7 +43,7 @@ Add dependencies ~~~~~~~~~~~~~~~~ Just like in :ref:`wiki_defining_views` we need a new dependency. -We need to add the ``bcrypt`` package, to our tutorial package's +We need to add the ``bcrypt`` [1]_ package, to our tutorial package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in the ``setup()`` function. @@ -81,15 +81,15 @@ request)`` returns ``None``. We will use ``groupfinder()`` as an :term:`authentication policy` "callback" that will provide the :term:`principal` or principals for a user. -There are two helper methods that will help us later when loging-in users. +There are two helper methods that will help us later to authenticate users. The first is ``hash_password`` which takes a raw password and transforms it using -bcrypt into an irreversible representation, a process known as "hashing". The +bcrypt_ into an irreversible representation, a process known as "hashing". The second method, ``check_password``, will allow us to compare the hashed value of the submitted password against the hashed value of the password stored in the user's record. If the two hashed values match, then the submitted password is valid, and we can authenticate the user. -We hash passwords so that it is impossible to decrypt them and use them to +We hash passwords so that it is impossible to decrypt and use them to authenticate in the application. If we stored passwords foolishly in clear text, then anyone with access to the database could retrieve any password to authenticate as any user. @@ -403,3 +403,11 @@ following URLs, checking that the result is as expected: the login form with the ``editor`` credentials), we'll see a Logout link in the upper right hand corner. When we click it, we're logged out, and redirected back to the front page. + + +.. _bcrypt: https://pypi.python.org/pypi/bcrypt + +.. [1] We are using the bcrypt_ package from PyPI to hash our passwords + securely. There are other one-way hash algorithms for passwords if + bcrypt is an issue on your system. Just make sure that it's an + algorithm approved for storing passwords versus a generic one-way hash. diff --git a/docs/tutorials/wiki/src/authorization/tutorial/security.py b/docs/tutorials/wiki/src/authorization/tutorial/security.py index 4115c780c..cbb3acd5d 100644 --- a/docs/tutorials/wiki/src/authorization/tutorial/security.py +++ b/docs/tutorials/wiki/src/authorization/tutorial/security.py @@ -2,11 +2,13 @@ import bcrypt def hash_password(pw): - return bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + hashed_pw = bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + # return unicode instead of bytes because databases handle it better + return hashed_pw.decode('utf-8') def check_password(expected_hash, pw): if expected_hash is not None: - return bcrypt.checkpw(pw.encode('utf-8'), expected_hash) + return bcrypt.checkpw(pw.encode('utf-8'), expected_hash.encode('utf-8')) return False USERS = {'editor': hash_password('editor'), diff --git a/docs/tutorials/wiki/src/tests/tutorial/security.py b/docs/tutorials/wiki/src/tests/tutorial/security.py index 4115c780c..cbb3acd5d 100644 --- a/docs/tutorials/wiki/src/tests/tutorial/security.py +++ b/docs/tutorials/wiki/src/tests/tutorial/security.py @@ -2,11 +2,13 @@ import bcrypt def hash_password(pw): - return bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + hashed_pw = bcrypt.hashpw(pw.encode('utf-8'), bcrypt.gensalt()) + # return unicode instead of bytes because databases handle it better + return hashed_pw.decode('utf-8') def check_password(expected_hash, pw): if expected_hash is not None: - return bcrypt.checkpw(pw.encode('utf-8'), expected_hash) + return bcrypt.checkpw(pw.encode('utf-8'), expected_hash.encode('utf-8')) return False USERS = {'editor': hash_password('editor'), -- cgit v1.2.3 From fad00d3201d9debd8abc146355a82d9adb6d823e Mon Sep 17 00:00:00 2001 From: Nejc Zupan Date: Wed, 7 Dec 2016 14:38:32 +0100 Subject: bring wiki2 test coverage up to 100%, refs #2451 --- .../src/tests/tutorial/scripts/initializedb.py | 1 + .../src/tests/tutorial/tests/test_functional.py | 12 ++++ .../wiki2/src/tests/tutorial/tests/test_initdb.py | 20 +++++++ .../src/tests/tutorial/tests/test_security.py | 21 +++++++ .../src/tests/tutorial/tests/test_user_model.py | 67 ++++++++++++++++++++++ 5 files changed, 121 insertions(+) create mode 100644 docs/tutorials/wiki2/src/tests/tutorial/tests/test_initdb.py create mode 100644 docs/tutorials/wiki2/src/tests/tutorial/tests/test_security.py create mode 100644 docs/tutorials/wiki2/src/tests/tutorial/tests/test_user_model.py diff --git a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py index f3c0a6fef..c860ef8cf 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/scripts/initializedb.py @@ -28,6 +28,7 @@ def usage(argv): def main(argv=sys.argv): if len(argv) < 2: usage(argv) + return config_uri = argv[1] options = parse_vars(argv[2:]) setup_logging(config_uri) diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py index 715768b2e..0250e71c9 100644 --- a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py +++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_functional.py @@ -11,6 +11,9 @@ class FunctionalTests(unittest.TestCase): basic_wrong_login = ( '/login?login=basic&password=incorrect' '&next=FrontPage&form.submitted=Login') + basic_login_no_next = ( + '/login?login=basic&password=basic' + '&form.submitted=Login') editor_login = ( '/login?login=editor&password=editor' '&next=FrontPage&form.submitted=Login') @@ -68,6 +71,10 @@ class FunctionalTests(unittest.TestCase): res = self.testapp.get(self.basic_login, status=302) self.assertEqual(res.location, 'http://localhost/FrontPage') + def test_successful_log_in_no_next(self): + res = self.testapp.get(self.basic_login_no_next, status=302) + self.assertEqual(res.location, 'http://localhost/') + def test_failed_log_in(self): res = self.testapp.get(self.basic_wrong_login, status=200) self.assertTrue(b'login' in res.body) @@ -120,3 +127,8 @@ class FunctionalTests(unittest.TestCase): self.testapp.get(self.editor_login, status=302) res = self.testapp.get('/FrontPage', status=200) self.assertTrue(b'FrontPage' in res.body) + + def test_redirect_to_edit_for_existing_page(self): + self.testapp.get(self.editor_login, status=302) + res = self.testapp.get('/add_page/FrontPage', status=302) + self.assertTrue(b'FrontPage' in res.body) diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_initdb.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_initdb.py new file mode 100644 index 000000000..97511d5e8 --- /dev/null +++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_initdb.py @@ -0,0 +1,20 @@ +import mock +import unittest + + +class TestInitializeDB(unittest.TestCase): + + @mock.patch('tutorial.scripts.initializedb.sys') + def test_usage(self, mocked_sys): + from ..scripts.initializedb import main + main(argv=['foo']) + mocked_sys.exit.assert_called_with(1) + + @mock.patch('tutorial.scripts.initializedb.get_tm_session') + @mock.patch('tutorial.scripts.initializedb.sys') + def test_run(self, mocked_sys, mocked_session): + from ..scripts.initializedb import main + main(argv=['foo', 'development.ini']) + mocked_session.assert_called_once() + + diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_security.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_security.py new file mode 100644 index 000000000..4c3b72946 --- /dev/null +++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_security.py @@ -0,0 +1,21 @@ +import mock +import unittest + + +class TestMyAuthenticationPolicy(unittest.TestCase): + + def test_no_user(self): + request = mock.Mock() + request.user = None + + from ..security import MyAuthenticationPolicy + policy = MyAuthenticationPolicy(None) + self.assertEqual(policy.authenticated_userid(request), None) + + def test_authenticated_user(self): + request = mock.Mock() + request.user.id = 'foo' + + from ..security import MyAuthenticationPolicy + policy = MyAuthenticationPolicy(None) + self.assertEqual(policy.authenticated_userid(request), 'foo') diff --git a/docs/tutorials/wiki2/src/tests/tutorial/tests/test_user_model.py b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_user_model.py new file mode 100644 index 000000000..9490ac990 --- /dev/null +++ b/docs/tutorials/wiki2/src/tests/tutorial/tests/test_user_model.py @@ -0,0 +1,67 @@ +import unittest +import transaction + +from pyramid import testing + + +class BaseTest(unittest.TestCase): + + def setUp(self): + from ..models import get_tm_session + self.config = testing.setUp(settings={ + 'sqlalchemy.url': 'sqlite:///:memory:' + }) + self.config.include('..models') + self.config.include('..routes') + + session_factory = self.config.registry['dbsession_factory'] + self.session = get_tm_session(session_factory, transaction.manager) + + self.init_database() + + def init_database(self): + from ..models.meta import Base + session_factory = self.config.registry['dbsession_factory'] + engine = session_factory.kw['bind'] + Base.metadata.create_all(engine) + + def tearDown(self): + testing.tearDown() + transaction.abort() + + def makeUser(self, name, role): + from ..models import User + return User(name=name, role=role) + + +class TestSetPassword(BaseTest): + + def test_password_hash_saved(self): + user = self.makeUser(name='foo', role='bar') + self.assertFalse(user.password_hash) + + user.set_password('secret') + self.assertTrue(user.password_hash) + + +class TestCheckPassword(BaseTest): + + def test_password_hash_not_set(self): + user = self.makeUser(name='foo', role='bar') + self.assertFalse(user.password_hash) + + self.assertFalse(user.check_password('secret')) + + def test_correct_password(self): + user = self.makeUser(name='foo', role='bar') + user.set_password('secret') + self.assertTrue(user.password_hash) + + self.assertTrue(user.check_password('secret')) + + def test_incorrect_password(self): + user = self.makeUser(name='foo', role='bar') + user.set_password('secret') + self.assertTrue(user.password_hash) + + self.assertFalse(user.check_password('incorrect')) -- cgit v1.2.3 From cfbc73dc042d924503527add9b32c48aa3ba29bd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Dec 2016 03:25:24 -0800 Subject: update typographical conventions per @bertjwregeer --- docs/typographical-conventions.rst | 89 -------------------------------------- 1 file changed, 89 deletions(-) diff --git a/docs/typographical-conventions.rst b/docs/typographical-conventions.rst index 5c7efea31..19894775b 100644 --- a/docs/typographical-conventions.rst +++ b/docs/typographical-conventions.rst @@ -28,32 +28,6 @@ A glossary defines terms used throughout the documentation. References to glossa Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term. -.. _typographical-conventions-headings: - -Headings --------- - -Sections, sub-sections, and sub-sub-sections within a web page or chapter are denoted with headings at various levels. The immediately preceding heading "Headings" is a section heading. Sub-section and sub-sub-section headings are shown as follows. - -Heading Level 2 -^^^^^^^^^^^^^^^ - -sub-section - -Heading Level 3 -""""""""""""""" - -sub-sub-section - - -.. _typographical-conventions-paragraphs: - -Paragraphs ----------- - -A paragraph of text looks exactly like this paragraph. - - .. _typographical-conventions-links: Links @@ -202,53 +176,6 @@ Inline code is displayed as follows, where the inline code is 'pip install -e ". Install requirements for building documentation: ``pip install -e ".[docs]"`` -.. _typographical-conventions-lists: - -Lists ------ - -Bulleted lists display as follows. - -* This is an item in a bulleted list. -* This is another item in a bulleted list. - -Numbered lists display as follows. - -#. This is an item in a numbered list. -#. This is another item in a numbered list. - -Nested lists display as follows. - -#. This is a list item in the parent list. -#. This is another list item in the parent list. - - #. This is a list item in the child list. - #. This is another list item in the child list. - -#. This is one more list item in the parent list. - - -.. _typographical-conventions-tables: - -Tables ------- - -Tables display as follows. - -===== ===== -col 1 col 2 -===== ===== -1 Second column of row 1. -2 Second column of row 2. - Second line of paragraph. -3 * Second column of row 3. - - * Second item in bullet - list (row 3, column 2). -\ Row 4; column 1 will be empty. -===== ===== - - .. _typographical-conventions-feature-versioning: Feature versioning @@ -350,22 +277,6 @@ Todo items designated tasks that require further work. This is a todo item. -.. _typographical-conventions-italics: - -Italics -------- - -This *word* is italicized. - - -.. _typographical-conventions-strong: - -Strong ------- - -This **word** is in bold text. - - .. _typographical-conventions-cross-references: Cross-references -- cgit v1.2.3 From 11d637f45e90c011ce15f7e016e909f0f300c705 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Dec 2016 03:50:59 -0800 Subject: add fixes for Sphinx 1.5 --- docs/conf.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 0e3f03068..12dd27722 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -196,10 +196,10 @@ latex_documents = [ # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -latex_use_parts = True +latex_toplevel_sectioning = "section" # If false, no module index is generated. -latex_use_modindex = False +latex_domain_indices = False ## Say, for a moment that you have a twoside document that needs a 3cm ## inner margin to allow for binding and at least two centimetres the -- cgit v1.2.3 From 3adaf31276f9c671ec469dee7dd115723f1eec3b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 8 Dec 2016 23:06:26 -0800 Subject: minor grammar and style fixes for wiki/authorization --- docs/tutorials/wiki/authorization.rst | 26 ++++++++++---------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/docs/tutorials/wiki/authorization.rst b/docs/tutorials/wiki/authorization.rst index 523acc53b..67af83b25 100644 --- a/docs/tutorials/wiki/authorization.rst +++ b/docs/tutorials/wiki/authorization.rst @@ -18,7 +18,7 @@ require permission, instead of a default "403 Forbidden" page. We will implement the access control with the following steps: -* Add password hashing dependencies +* Add password hashing dependencies. * Add users and groups (``security.py``, a new module). * Add an :term:`ACL` (``models.py``). * Add an :term:`authentication policy` and an :term:`authorization policy` @@ -39,13 +39,11 @@ Then we will add the login and logout feature: Access control -------------- + Add dependencies ~~~~~~~~~~~~~~~~ -Just like in :ref:`wiki_defining_views` we need a new dependency. -We need to add the ``bcrypt`` [1]_ package, to our tutorial package's -``setup.py`` file by assigning this dependency to the ``requires`` parameter -in the ``setup()`` function. +Just like in :ref:`wiki_defining_views`, we need a new dependency. We need to add the `bcrypt `_ package, to our tutorial package's ``setup.py`` file by assigning this dependency to the ``requires`` parameter in the ``setup()`` function. Open ``setup.py`` and edit it to look like the following: @@ -58,11 +56,15 @@ Only the highlighted line needs to be added. Do not forget to run ``pip install -e .`` just like in :ref:`wiki-running-pip-install`. +.. note:: + + We are using the ``bcrypt`` package from PyPI to hash our passwords securely. There are other one-way hash algorithms for passwords if bcrypt is an issue on your system. Just make sure that it's an algorithm approved for storing passwords versus a generic one-way hash. + + Add users and groups ~~~~~~~~~~~~~~~~~~~~ -Create a new ``tutorial/security.py`` module with the -following content: +Create a new ``tutorial/security.py`` module with the following content: .. literalinclude:: src/authorization/tutorial/security.py :linenos: @@ -83,7 +85,7 @@ request)`` returns ``None``. We will use ``groupfinder()`` as an There are two helper methods that will help us later to authenticate users. The first is ``hash_password`` which takes a raw password and transforms it using -bcrypt_ into an irreversible representation, a process known as "hashing". The +bcrypt into an irreversible representation, a process known as "hashing". The second method, ``check_password``, will allow us to compare the hashed value of the submitted password against the hashed value of the password stored in the user's record. If the two hashed values match, then the submitted @@ -403,11 +405,3 @@ following URLs, checking that the result is as expected: the login form with the ``editor`` credentials), we'll see a Logout link in the upper right hand corner. When we click it, we're logged out, and redirected back to the front page. - - -.. _bcrypt: https://pypi.python.org/pypi/bcrypt - -.. [1] We are using the bcrypt_ package from PyPI to hash our passwords - securely. There are other one-way hash algorithms for passwords if - bcrypt is an issue on your system. Just make sure that it's an - algorithm approved for storing passwords versus a generic one-way hash. -- cgit v1.2.3 From 40ab35b67d2b563b096d99941b0ddb0aedd47524 Mon Sep 17 00:00:00 2001 From: Pavlo Kapyshin Date: Fri, 9 Dec 2016 17:34:15 +0200 Subject: Fix typo --- docs/whatsnew-1.7.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/whatsnew-1.7.rst b/docs/whatsnew-1.7.rst index 398b12f01..c5f611f04 100644 --- a/docs/whatsnew-1.7.rst +++ b/docs/whatsnew-1.7.rst @@ -126,7 +126,7 @@ Feature Additions - The :attr:`pyramid.tweens.EXCVIEW` tween will now re-raise the original exception if no exception view could be found to handle it. This allows - the exception to be handled upstream by another tween or middelware. + the exception to be handled upstream by another tween or middleware. See https://github.com/Pylons/pyramid/pull/2567 Deprecations -- cgit v1.2.3 From 80865ce4b2dee27d0be3868219fc447940ab1858 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Fri, 9 Dec 2016 22:16:49 -0700 Subject: Use has_body so we don't unravel app_iter This allows streaming responses. Closes #2625 --- pyramid/httpexceptions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyramid/httpexceptions.py b/pyramid/httpexceptions.py index 054917dfa..a22b088c6 100644 --- a/pyramid/httpexceptions.py +++ b/pyramid/httpexceptions.py @@ -246,7 +246,7 @@ ${body}''') 'title': self.title} def prepare(self, environ): - if not self.body and not self.empty_body: + if not self.has_body and not self.empty_body: html_comment = '' comment = self.comment or '' accept_value = environ.get('HTTP_ACCEPT', '') -- cgit v1.2.3 From 2ae320a4390940014dd049d2fc5f8312a31e2961 Mon Sep 17 00:00:00 2001 From: Bert JW Regeer Date: Fri, 9 Dec 2016 22:18:21 -0700 Subject: Pin to a newer version of WebOb v1.7.0 has property Response.has_body --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index a6dbc2824..383991d73 100644 --- a/setup.py +++ b/setup.py @@ -41,7 +41,7 @@ except IOError: install_requires = [ 'setuptools', - 'WebOb >= 1.3.1', # request.domain and CookieProfile + 'WebOb >= 1.7.0rc2', # Response.has_body 'repoze.lru >= 0.4', # py3 compat 'zope.interface >= 3.8.0', # has zope.interface.registry 'zope.deprecation >= 3.5.0', # py3 compat -- cgit v1.2.3 From 2d45def603f038a8533eb9790640982012c0be30 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Fri, 9 Dec 2016 23:41:25 -0600 Subject: add changelog for #2863 --- CHANGES.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/CHANGES.txt b/CHANGES.txt index 9daddff48..f3883b557 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -119,6 +119,12 @@ Features See https://github.com/Pylons/pyramid/pull/2805 +- Allow streaming responses to be made from subclasses of + ``pyramid.httpexceptions.HTTPException``. Previously the response would + be unrolled while testing for a body, making it impossible to stream + a response. + See https://github.com/Pylons/pyramid/pull/2863 + Bug Fixes --------- -- cgit v1.2.3 From bff312df8c36ac3ef5389a89c7459b282f944f77 Mon Sep 17 00:00:00 2001 From: Matthew Wilkes Date: Thu, 8 Dec 2016 15:00:29 +0100 Subject: Fix bug where plural rules would not be loaded for the default 'messages' domain. --- CHANGES.txt | 5 +++++ pyramid/i18n.py | 12 +++++++++++- pyramid/tests/test_i18n.py | 30 ++++++++++++++++++++++++++++++ 3 files changed, 46 insertions(+), 1 deletion(-) diff --git a/CHANGES.txt b/CHANGES.txt index 65a1f15cd..2dc80c005 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -149,6 +149,11 @@ Bug Fixes from previous orders have executed. See https://github.com/Pylons/pyramid/pull/2757 +- Fix bug in i18n where the default domain would always use the Germanic plural + style, even if a different plural function is defined in the relevant messages + file. + See https://github.com/Pylons/pyramid/pull/2102 + Deprecations ------------ diff --git a/pyramid/i18n.py b/pyramid/i18n.py index 79209d342..1d11adfe3 100644 --- a/pyramid/i18n.py +++ b/pyramid/i18n.py @@ -22,6 +22,7 @@ from pyramid.threadlocal import get_current_registry TranslationString = TranslationString # PyFlakes TranslationStringFactory = TranslationStringFactory # PyFlakes +DEFAULT_PLURAL = lambda n: int(n != 1) class Localizer(object): """ @@ -233,7 +234,13 @@ class Translations(gettext.GNUTranslations, object): # GNUTranslations._parse (called as a side effect if fileobj is # passed to GNUTranslations.__init__) with a "real" self.plural for # this domain; see https://github.com/Pylons/pyramid/issues/235 - self.plural = lambda n: int(n != 1) + # It is only overridden the first time a new message file is found + # for a given domain, so all message files must have matching plural + # rules if they are in the same domain. We keep track of if we have + # overridden so we can special case the default domain, which is always + # instantiated before a message file is read. + # See also https://github.com/Pylons/pyramid/pull/2102 + self.plural = DEFAULT_PLURAL gettext.GNUTranslations.__init__(self, fp=fileobj) self.files = list(filter(None, [getattr(fileobj, 'name', None)])) self.domain = domain @@ -285,6 +292,9 @@ class Translations(gettext.GNUTranslations, object): :rtype: `Translations` """ domain = getattr(translations, 'domain', self.DEFAULT_DOMAIN) + if domain == self.DEFAULT_DOMAIN and self.plural is DEFAULT_PLURAL: + self.plural = translations.plural + if merge and domain == self.domain: return self.merge(translations) diff --git a/pyramid/tests/test_i18n.py b/pyramid/tests/test_i18n.py index 67b2ac356..d72d0d480 100644 --- a/pyramid/tests/test_i18n.py +++ b/pyramid/tests/test_i18n.py @@ -357,6 +357,36 @@ class TestTranslations(unittest.TestCase): inst.add(inst2) self.assertEqual(inst._catalog['a'], 'b') + def test_add_default_domain_replaces_plural_first_time(self): + # Create three empty message catalogs in the default domain + inst = self._getTargetClass()(None, domain='messages') + inst2 = self._getTargetClass()(None, domain='messages') + inst3 = self._getTargetClass()(None, domain='messages') + inst._catalog = {} + inst2._catalog = {} + inst3._catalog = {} + + # The default plural scheme is the germanic one + self.assertEqual(inst.plural(0), 1) + self.assertEqual(inst.plural(1), 0) + self.assertEqual(inst.plural(2), 1) + + # inst2 represents a message file that declares french plurals + inst2.plural = lambda n: n > 1 + inst.add(inst2) + # that plural rule should now apply to inst + self.assertEqual(inst.plural(0), 0) + self.assertEqual(inst.plural(1), 0) + self.assertEqual(inst.plural(2), 1) + + # We load a second message file with different plural rules + inst3.plural = lambda n: n > 0 + inst.add(inst3) + # It doesn't override the previously loaded rule + self.assertEqual(inst.plural(0), 0) + self.assertEqual(inst.plural(1), 0) + self.assertEqual(inst.plural(2), 1) + def test_dgettext(self): t = self._makeOne() self.assertEqual(t.dgettext('messages', 'foo'), 'Voh') -- cgit v1.2.3 From 6421f4c7559205e125a1c7218f711d6f6ecaf85c Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Mon, 12 Dec 2016 11:13:08 -0600 Subject: reference the correct PR for #2859 --- CHANGES.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 0a810a0d6..8a6713783 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -160,9 +160,8 @@ Bug Fixes See https://github.com/Pylons/pyramid/pull/2757 - Fix bug in i18n where the default domain would always use the Germanic plural - style, even if a different plural function is defined in the relevant messages - file. - See https://github.com/Pylons/pyramid/pull/2102 + style, even if a different plural function is defined in the relevant + messages file. See https://github.com/Pylons/pyramid/pull/2859 Deprecations ------------ -- cgit v1.2.3 From b7b18463b80b9f16d603264c3b1b661061f492e6 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 13 Dec 2016 12:42:00 -0800 Subject: revert commits for ZODB scaffold changes --- pyramid/scaffolds/zodb/+package+/__init__.py | 2 +- .../zodb/+package+/templates/layout.jinja2_tmpl | 66 --------------------- .../+package+/templates/mytemplate.jinja2_tmpl | 7 --- .../zodb/+package+/templates/mytemplate.pt_tmpl | 67 ++++++++++++++++++++++ pyramid/scaffolds/zodb/+package+/views.py_tmpl | 2 +- pyramid/scaffolds/zodb/MANIFEST.in_tmpl | 2 +- pyramid/scaffolds/zodb/setup.py_tmpl | 2 +- 7 files changed, 71 insertions(+), 77 deletions(-) delete mode 100644 pyramid/scaffolds/zodb/+package+/templates/layout.jinja2_tmpl delete mode 100644 pyramid/scaffolds/zodb/+package+/templates/mytemplate.jinja2_tmpl create mode 100644 pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt_tmpl diff --git a/pyramid/scaffolds/zodb/+package+/__init__.py b/pyramid/scaffolds/zodb/+package+/__init__.py index 0ca5198b6..f2a86df47 100644 --- a/pyramid/scaffolds/zodb/+package+/__init__.py +++ b/pyramid/scaffolds/zodb/+package+/__init__.py @@ -12,7 +12,7 @@ def main(global_config, **settings): """ This function returns a Pyramid WSGI application. """ config = Configurator(root_factory=root_factory, settings=settings) - config.include('pyramid_jinja2') + config.include('pyramid_chameleon') config.add_static_view('static', 'static', cache_max_age=3600) config.scan() return config.make_wsgi_app() diff --git a/pyramid/scaffolds/zodb/+package+/templates/layout.jinja2_tmpl b/pyramid/scaffolds/zodb/+package+/templates/layout.jinja2_tmpl deleted file mode 100644 index a0b3f22f4..000000000 --- a/pyramid/scaffolds/zodb/+package+/templates/layout.jinja2_tmpl +++ /dev/null @@ -1,66 +0,0 @@ - - - - - - - - - - - ZODB Scaffold for The Pyramid Web Framework - - - - - - - - - - - - - -
-
-
-
- -
-
- {% block content %} -
No content
- {% endblock content %} -
-
-
-
-
-
Generated by v{{pyramid_version}}
-
Docs
-
Github Project
-
IRC Channel
-
Pylons Project
-
-
-
-
-
- Copyright © Pylons Project -
-
-
-
- - - - - - - - diff --git a/pyramid/scaffolds/zodb/+package+/templates/mytemplate.jinja2_tmpl b/pyramid/scaffolds/zodb/+package+/templates/mytemplate.jinja2_tmpl deleted file mode 100644 index bb075e91d..000000000 --- a/pyramid/scaffolds/zodb/+package+/templates/mytemplate.jinja2_tmpl +++ /dev/null @@ -1,7 +0,0 @@ -{% extends "layout.jinja2" %} -{% block content %} -
-
Pyramid ZODB scaffold
-
Welcome to \{\{project\}\}, an application generated by
the Pyramid Web Framework {{pyramid_version}}.
-
-{% endblock content %} diff --git a/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt_tmpl b/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt_tmpl new file mode 100644 index 000000000..e109ab829 --- /dev/null +++ b/pyramid/scaffolds/zodb/+package+/templates/mytemplate.pt_tmpl @@ -0,0 +1,67 @@ + + + + + + + + + + + ZODB Scaffold for The Pyramid Web Framework + + + + + + + + + + + + + +
+
+
+
+ +
+
+
+
Pyramid ZODB scaffold
+
Welcome to ${project}, an application generated by
the Pyramid Web Framework {{pyramid_version}}.
+
+
+
+
+
+
+
Generated by v{{pyramid_version}}
+
Docs
+
Github Project
+
IRC Channel
+
Pylons Project
+
+
+
+
+
+ Copyright © Pylons Project +
+
+
+
+ + + + + + + + diff --git a/pyramid/scaffolds/zodb/+package+/views.py_tmpl b/pyramid/scaffolds/zodb/+package+/views.py_tmpl index 0b176b365..1e8a9b65a 100644 --- a/pyramid/scaffolds/zodb/+package+/views.py_tmpl +++ b/pyramid/scaffolds/zodb/+package+/views.py_tmpl @@ -2,6 +2,6 @@ from pyramid.view import view_config from .models import MyModel -@view_config(context=MyModel, renderer='templates/mytemplate.jinja2') +@view_config(context=MyModel, renderer='templates/mytemplate.pt') def my_view(request): return {'project': '{{project}}'} diff --git a/pyramid/scaffolds/zodb/MANIFEST.in_tmpl b/pyramid/scaffolds/zodb/MANIFEST.in_tmpl index 4d1c86b44..0ff6eb7a0 100644 --- a/pyramid/scaffolds/zodb/MANIFEST.in_tmpl +++ b/pyramid/scaffolds/zodb/MANIFEST.in_tmpl @@ -1,2 +1,2 @@ include *.txt *.ini *.cfg *.rst -recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml *.jinja2 +recursive-include {{package}} *.ico *.png *.css *.gif *.jpg *.pt *.txt *.mak *.mako *.js *.html *.xml diff --git a/pyramid/scaffolds/zodb/setup.py_tmpl b/pyramid/scaffolds/zodb/setup.py_tmpl index a503d60ab..19771d756 100644 --- a/pyramid/scaffolds/zodb/setup.py_tmpl +++ b/pyramid/scaffolds/zodb/setup.py_tmpl @@ -10,7 +10,7 @@ with open(os.path.join(here, 'CHANGES.txt')) as f: requires = [ 'pyramid', - 'pyramid_jinja2', + 'pyramid_chameleon', 'pyramid_debugtoolbar', 'pyramid_tm', 'pyramid_zodbconn', -- cgit v1.2.3 From 760cf2c1c6b0e5e098528d9229809a46c0a9d24d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 13 Dec 2016 12:46:50 -0800 Subject: resolve conflict in CONTRIBUTORS.txt --- CONTRIBUTORS.txt | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTORS.txt b/CONTRIBUTORS.txt index dcca62d48..93e526830 100644 --- a/CONTRIBUTORS.txt +++ b/CONTRIBUTORS.txt @@ -285,4 +285,8 @@ Contributors - Keith Yang, 2016/07/22 -- Hannah Krager, 2016/10/22 \ No newline at end of file +- Hannah Krager, 2016/10/22 + +- Moriyoshi Koizumi, 2016/11/20 + +- Mikko Ohtamaa, 2016/12/6 -- cgit v1.2.3 From 4393f8b8e54e636b5655e0a8d2477e0b15820f68 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 13 Dec 2016 13:12:02 -0800 Subject: capitalize Pylons --- pyramid/scripts/pcreate.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyramid/scripts/pcreate.py b/pyramid/scripts/pcreate.py index 52f8fea5e..825d8741b 100644 --- a/pyramid/scripts/pcreate.py +++ b/pyramid/scripts/pcreate.py @@ -27,7 +27,7 @@ Render Pyramid scaffolding to an output directory. Note: As of Pyramid 1.8, this command is deprecated. Use a specific cookiecutter instead: -https://github.com/pylons/?query=cookiecutter +https://github.com/Pylons/?query=cookiecutter """ usage = "usage: %prog [options] -s output_directory" parser = optparse.OptionParser(usage, description=description) -- cgit v1.2.3 From fd89d18d887576ca7d818f069b6bfad524c3e3ea Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 13 Dec 2016 13:30:29 -0800 Subject: fix query string --- pyramid/scripts/pcreate.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyramid/scripts/pcreate.py b/pyramid/scripts/pcreate.py index 595fd8d77..b3e3b65fa 100644 --- a/pyramid/scripts/pcreate.py +++ b/pyramid/scripts/pcreate.py @@ -27,7 +27,7 @@ Render Pyramid scaffolding to an output directory. Note: As of Pyramid 1.8, this command is deprecated. Use a specific cookiecutter instead: -https://github.com/Pylons/?query=cookiecutter +https://github.com/Pylons/?q=cookiecutter """ usage = "usage: %prog [options] -s output_directory" parser = optparse.OptionParser(usage, description=description) -- cgit v1.2.3 From 8dfa640a52d57b630843a65b3b84bc13a8a1ed87 Mon Sep 17 00:00:00 2001 From: Michael Merickel Date: Wed, 14 Dec 2016 00:21:22 -0600 Subject: fix holdover from chameleon in starter layout --- pyramid/scaffolds/starter/+package+/templates/layout.jinja2_tmpl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyramid/scaffolds/starter/+package+/templates/layout.jinja2_tmpl b/pyramid/scaffolds/starter/+package+/templates/layout.jinja2_tmpl index 360855602..6f0cfd2fa 100644 --- a/pyramid/scaffolds/starter/+package+/templates/layout.jinja2_tmpl +++ b/pyramid/scaffolds/starter/+package+/templates/layout.jinja2_tmpl @@ -6,7 +6,7 @@ - + Starter Scaffold for The Pyramid Web Framework -- cgit v1.2.3