Typographical Conventions¶
Introduction¶
This chapter describes typographical conventions used in the Pyramid documentation.
Glossary¶
A glossary defines terms used throughout the documentation. References to glossary terms appear as follows.
Note it is hyperlinked, and when clicked it will take the user to the term in the Glossary and highlight the term.
Links¶
Links are presented as follows, and may be clickable.
See also
See also Cross-references for other links within the documentation.
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.
Code¶
Code may be displayed in blocks or inline. Blocks of code may use syntax highlighting, line numbering, and emphasis.
Syntax highlighting¶
XML:
<somesnippet>Some XML</somesnippet>
Unix shell commands (See venv for the meaning of $VENV.):
$VENV/bin/pip install -e .
Windows commands (See venv for the meaning of %VENV%.):
%VENV%\Scripts\pserve development.ini
cfg:
[some-part]
# A random part in the buildout
recipe = collective.recipe.foo
option = value
ini:
[tool:pytest]
python_files = test_*.py
testpaths =
tests
addopts = -W always
Interactive Python:
>>> class Foo:
... bar = 100
...
>>> f = Foo()
>>> f.bar
100
>>> f.bar / 0
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ZeroDivisionError: integer division or modulo by zero
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:
$VENV/bin/pytest tutorial/tests.py --cov-report term-missing \
--cov=tutorial -q
Code block options¶
To emphasize lines, we give the appearance that a highlighting pen has been used on the code.
if "foo" == "bar":
# This is Python code
pass
A code block with line numbers.
1if "foo" == "bar":
2 # This is Python code
3 pass
Some code blocks may be given a caption.
if "foo" == "bar":
# This is Python code
pass
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]"
Feature versioning¶
We designate the version in which something is added, changed, or deprecated in the project.
Version added¶
The version in which a feature is added to a project is displayed as follows.
New in version 1.1: pyramid.paster.bootstrap()
Version changed¶
The version in which a feature is changed in a project is displayed as follows.
Changed in version 1.8: Added the ability for bootstrap to cleanup automatically via the with statement.
Deprecated¶
The version in which a feature is deprecated in a project is displayed as follows.
Deprecated since version 1.7: Use the require_csrf option or read Checking CSRF Tokens Automatically instead to have pyramid.exceptions.BadCSRFToken exceptions raised.
Warnings¶
Warnings represent limitations and advice related to a topic or concept.
Warning
This is a warning.
Notes¶
Notes represent additional information related to a topic or concept.
Note
This is a note.
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.
See also
Cross-references¶
Cross-references are links that may be to a document, arbitrary location, object, or other items.
Cross-referencing documents¶
Links to pages within this documentation display as follows.
Cross-referencing arbitrary locations¶
Links to sections, and tables and figures with captions, within this documentation display as follows.
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.
Python class names display as follows.
Python method names display as follows.
pyramid.config.Configurator.add_view()
Python function names display as follows.
pyramid.renderers.render_to_response()
Sometimes we show only the last segment of a Python object's name, which displays as follows.
The application "Pyramid" itself displays as follows.
Pyramid