commit | author | age
|
b99ada
|
1 |
.. _typographical-conventions: |
SP |
2 |
|
|
3 |
Typographical Conventions |
|
4 |
========================= |
|
5 |
|
|
6 |
.. meta:: |
|
7 |
:description: This chapter describes typographical conventions used in the Pyramid documentation. |
|
8 |
:keywords: Pyramid, Typographical Conventions |
|
9 |
|
|
10 |
|
|
11 |
.. _typographical-conventions-introduction: |
|
12 |
|
|
13 |
Introduction |
|
14 |
------------ |
|
15 |
|
4584c7
|
16 |
This chapter describes typographical conventions used in the Pyramid documentation. |
b99ada
|
17 |
|
SP |
18 |
|
|
19 |
.. _typographical-conventions-glossary: |
|
20 |
|
|
21 |
Glossary |
|
22 |
-------- |
|
23 |
|
|
24 |
A glossary defines terms used throughout the documentation. References to glossary terms appear as follows. |
|
25 |
|
|
26 |
:term:`request` |
|
27 |
|
|
28 |
Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term. |
|
29 |
|
|
30 |
|
|
31 |
.. _typographical-conventions-links: |
|
32 |
|
|
33 |
Links |
|
34 |
----- |
|
35 |
|
|
36 |
Links are presented as follows, and may be clickable. |
|
37 |
|
7b1612
|
38 |
`TryPyramid <https://trypyramid.com>`_ |
b99ada
|
39 |
|
SP |
40 |
.. seealso:: See also :ref:`typographical-conventions-cross-references` for other links within the documentation. |
|
41 |
|
|
42 |
|
|
43 |
.. _typographical-conventions-topic: |
|
44 |
|
|
45 |
Topic |
|
46 |
----- |
|
47 |
|
|
48 |
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. |
|
49 |
|
|
50 |
.. topic:: Topic Title |
|
51 |
|
|
52 |
Subsequent indented lines comprise |
|
53 |
the body of the topic, and are |
|
54 |
interpreted as body elements. |
|
55 |
|
|
56 |
|
|
57 |
.. _typographical-conventions-displaying-code: |
|
58 |
|
|
59 |
Code |
|
60 |
---- |
|
61 |
|
|
62 |
Code may be displayed in blocks or inline. Blocks of code may use syntax highlighting, line numbering, and emphasis. |
|
63 |
|
|
64 |
|
|
65 |
.. _typographical-conventions-syntax-highlighting: |
|
66 |
|
|
67 |
Syntax highlighting |
|
68 |
^^^^^^^^^^^^^^^^^^^ |
|
69 |
|
|
70 |
XML: |
|
71 |
|
|
72 |
.. code-block:: xml |
|
73 |
|
|
74 |
<somesnippet>Some XML</somesnippet> |
|
75 |
|
|
76 |
Unix shell commands are prefixed with a ``$`` character. (See :term:`venv` for the meaning of ``$VENV``.) |
|
77 |
|
|
78 |
.. code-block:: bash |
|
79 |
|
|
80 |
$ $VENV/bin/pip install -e . |
|
81 |
|
|
82 |
Windows commands are prefixed with a drive letter with an optional directory name. (See :term:`venv` for the meaning of ``%VENV%``.) |
|
83 |
|
|
84 |
.. code-block:: doscon |
|
85 |
|
d81ed3
|
86 |
c:\> %VENV%\Scripts\pserve development.ini |
b99ada
|
87 |
|
SP |
88 |
cfg: |
|
89 |
|
|
90 |
.. code-block:: cfg |
|
91 |
|
|
92 |
[some-part] |
|
93 |
# A random part in the buildout |
|
94 |
recipe = collective.recipe.foo |
|
95 |
option = value |
|
96 |
|
|
97 |
ini: |
|
98 |
|
|
99 |
.. code-block:: ini |
|
100 |
|
|
101 |
[nosetests] |
|
102 |
match=^test |
|
103 |
where=pyramid |
|
104 |
nocapture=1 |
|
105 |
|
|
106 |
Interactive Python: |
|
107 |
|
|
108 |
.. code-block:: pycon |
|
109 |
|
|
110 |
>>> class Foo: |
|
111 |
... bar = 100 |
|
112 |
... |
|
113 |
>>> f = Foo() |
|
114 |
>>> f.bar |
|
115 |
100 |
|
116 |
>>> f.bar / 0 |
|
117 |
Traceback (most recent call last): |
|
118 |
File "<stdin>", line 1, in <module> |
|
119 |
ZeroDivisionError: integer division or modulo by zero |
|
120 |
|
|
121 |
|
|
122 |
.. _typographical-conventions-long-commands: |
|
123 |
|
|
124 |
Displaying long commands |
|
125 |
^^^^^^^^^^^^^^^^^^^^^^^^ |
|
126 |
|
|
127 |
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: |
|
128 |
|
|
129 |
.. code-block:: bash |
|
130 |
|
|
131 |
$ $VENV/bin/py.test tutorial/tests.py --cov-report term-missing \ |
|
132 |
--cov=tutorial -q |
|
133 |
|
|
134 |
|
|
135 |
.. _typographical-conventions-code-block-options: |
|
136 |
|
|
137 |
Code block options |
|
138 |
^^^^^^^^^^^^^^^^^^ |
|
139 |
|
|
140 |
To emphasize lines, we give the appearance that a highlighting pen has been used on the code. |
|
141 |
|
|
142 |
.. code-block:: python |
|
143 |
:emphasize-lines: 1,3 |
|
144 |
|
|
145 |
if "foo" == "bar": |
|
146 |
# This is Python code |
|
147 |
pass |
|
148 |
|
|
149 |
A code block with line numbers. |
|
150 |
|
|
151 |
.. code-block:: python |
|
152 |
:linenos: |
|
153 |
|
|
154 |
if "foo" == "bar": |
|
155 |
# This is Python code |
|
156 |
pass |
|
157 |
|
|
158 |
Some code blocks may be given a caption. |
|
159 |
|
|
160 |
.. code-block:: python |
|
161 |
:caption: sample.py |
fa8425
|
162 |
:name: sample-py-typographical-conventions |
b99ada
|
163 |
|
SP |
164 |
if "foo" == "bar": |
|
165 |
# This is Python code |
|
166 |
pass |
|
167 |
|
|
168 |
|
|
169 |
.. _typographical-conventions-inline-code: |
|
170 |
|
|
171 |
Inline code |
|
172 |
^^^^^^^^^^^ |
|
173 |
|
|
174 |
Inline code is displayed as follows, where the inline code is 'pip install -e ".[docs]"'. |
|
175 |
|
|
176 |
Install requirements for building documentation: ``pip install -e ".[docs]"`` |
|
177 |
|
|
178 |
|
|
179 |
.. _typographical-conventions-feature-versioning: |
|
180 |
|
|
181 |
Feature versioning |
|
182 |
------------------ |
|
183 |
|
|
184 |
We designate the version in which something is added, changed, or deprecated in the project. |
|
185 |
|
|
186 |
|
|
187 |
.. _typographical-conventions-version-added: |
|
188 |
|
|
189 |
Version added |
|
190 |
^^^^^^^^^^^^^ |
|
191 |
|
|
192 |
The version in which a feature is added to a project is displayed as follows. |
|
193 |
|
|
194 |
.. versionadded:: 1.1 |
|
195 |
:func:`pyramid.paster.bootstrap` |
|
196 |
|
|
197 |
|
|
198 |
.. _typographical-conventions-version-changed: |
|
199 |
|
|
200 |
Version changed |
|
201 |
^^^^^^^^^^^^^^^ |
|
202 |
|
|
203 |
The version in which a feature is changed in a project is displayed as follows. |
|
204 |
|
|
205 |
.. versionchanged:: 1.8 |
|
206 |
Added the ability for ``bootstrap`` to cleanup automatically via the ``with`` statement. |
|
207 |
|
|
208 |
|
|
209 |
.. _typographical-conventions-deprecated: |
|
210 |
|
|
211 |
Deprecated |
|
212 |
^^^^^^^^^^ |
|
213 |
|
|
214 |
The version in which a feature is deprecated in a project is displayed as follows. |
|
215 |
|
|
216 |
.. deprecated:: 1.7 |
|
217 |
Use the ``require_csrf`` option or read :ref:`auto_csrf_checking` instead to have :class:`pyramid.exceptions.BadCSRFToken` exceptions raised. |
|
218 |
|
|
219 |
|
|
220 |
.. _typographical-conventions-danger: |
|
221 |
|
|
222 |
Danger |
|
223 |
------ |
|
224 |
|
|
225 |
Danger represents critical information related to a topic or concept, and should recommend to the user "don't do this dangerous thing". |
|
226 |
|
|
227 |
.. danger:: |
|
228 |
|
|
229 |
This is danger or an error. |
|
230 |
|
|
231 |
|
|
232 |
.. _typographical-conventions-warnings: |
|
233 |
|
|
234 |
Warnings |
|
235 |
-------- |
|
236 |
|
|
237 |
Warnings represent limitations and advice related to a topic or concept. |
|
238 |
|
|
239 |
.. warning:: |
|
240 |
|
|
241 |
This is a warning. |
|
242 |
|
|
243 |
|
|
244 |
.. _typographical-conventions-notes: |
|
245 |
|
|
246 |
Notes |
|
247 |
----- |
|
248 |
|
|
249 |
Notes represent additional information related to a topic or concept. |
|
250 |
|
|
251 |
.. note:: |
|
252 |
|
|
253 |
This is a note. |
|
254 |
|
|
255 |
|
|
256 |
.. _typographical-conventions-see-also: |
|
257 |
|
|
258 |
See also |
|
259 |
-------- |
|
260 |
|
|
261 |
"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. |
|
262 |
|
|
263 |
.. seealso:: |
|
264 |
|
|
265 |
See :ref:`Quick Tutorial section on Requirements <qtut_requirements>`. |
|
266 |
|
|
267 |
|
|
268 |
.. _typographical-conventions-todo: |
|
269 |
|
|
270 |
Todo |
|
271 |
---- |
|
272 |
|
|
273 |
Todo items designated tasks that require further work. |
|
274 |
|
|
275 |
.. todo:: |
|
276 |
|
|
277 |
This is a todo item. |
|
278 |
|
|
279 |
|
|
280 |
.. _typographical-conventions-cross-references: |
|
281 |
|
|
282 |
Cross-references |
|
283 |
---------------- |
|
284 |
|
|
285 |
Cross-references are links that may be to a document, arbitrary location, object, or other items. |
|
286 |
|
|
287 |
|
|
288 |
.. _typographical-conventions-cross-referencing-documents: |
|
289 |
|
|
290 |
Cross-referencing documents |
|
291 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
292 |
|
|
293 |
Links to pages within this documentation display as follows. |
|
294 |
|
|
295 |
:doc:`quick_tour` |
|
296 |
|
|
297 |
|
|
298 |
.. _typographical-conventions-cross-referencing-arbitrary-locations: |
|
299 |
|
|
300 |
Cross-referencing arbitrary locations |
|
301 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
302 |
|
|
303 |
Links to sections, and tables and figures with captions, within this documentation display as follows. |
|
304 |
|
|
305 |
:ref:`i18n_chapter` |
|
306 |
|
|
307 |
|
|
308 |
.. _typographical-conventions-cross-referencing-python: |
|
309 |
|
|
310 |
Python modules, classes, methods, and functions |
|
311 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
|
312 |
|
|
313 |
All of the following are clickable links to Python modules, classes, methods, and functions. |
|
314 |
|
|
315 |
Python module names display as follows. |
|
316 |
|
|
317 |
:mod:`pyramid.config` |
|
318 |
|
|
319 |
Python class names display as follows. |
|
320 |
|
|
321 |
:class:`pyramid.config.Configurator` |
|
322 |
|
|
323 |
Python method names display as follows. |
|
324 |
|
|
325 |
:meth:`pyramid.config.Configurator.add_view` |
|
326 |
|
|
327 |
Python function names display as follows. |
|
328 |
|
|
329 |
:func:`pyramid.renderers.render_to_response` |
|
330 |
|
|
331 |
Sometimes we show only the last segment of a Python object's name, which displays as follows. |
|
332 |
|
|
333 |
:func:`~pyramid.renderers.render_to_response` |
|
334 |
|
|
335 |
The application "Pyramid" itself displays as follows. |
|
336 |
|
|
337 |
:app:`Pyramid` |
|
338 |
|