1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
.. _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 <http://www.pylonsproject.org/community/how-to-contribute>`_ and `Coding Style and Standards <http://docs.pylonsproject.org/en/latest/community/codestyle.html>`_.
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 <https://github.com/Pylons/pyramid/blob/master/contributing.md#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 <https://github.com/Pylons/pyramid/blob/master/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-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.
.. _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.
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 <http://www.pylonsproject.org>`_
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.
|
