| 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 | ||
| a816a8 | 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 | ||
| 510b21 | 76 | Unix shell commands (See :term:`venv` for the meaning of ``$VENV``.): |
| b99ada | 77 | |
| SP | 78 | .. code-block:: bash |
| 79 | ||
| 510b21 | 80 | $VENV/bin/pip install -e . |
| b99ada | 81 | |
| 510b21 | 82 | Windows commands (See :term:`venv` for the meaning of ``%VENV%``.): |
| b99ada | 83 | |
| SP | 84 | .. code-block:: doscon |
| 85 | ||
| 510b21 | 86 | %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 | ||
| 0f9ea0 | 131 | $VENV/bin/pytest tutorial/tests.py --cov-report term-missing \ |
| b99ada | 132 | --cov=tutorial -q |
| SP | 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-warnings: | |
| 221 | ||
| 222 | Warnings | |
| 223 | -------- | |
| 224 | ||
| 225 | Warnings represent limitations and advice related to a topic or concept. | |
| 226 | ||
| 227 | .. warning:: | |
| 228 | ||
| 229 | This is a warning. | |
| 230 | ||
| 231 | ||
| 232 | .. _typographical-conventions-notes: | |
| 233 | ||
| 234 | Notes | |
| 235 | ----- | |
| 236 | ||
| 237 | Notes represent additional information related to a topic or concept. | |
| 238 | ||
| 239 | .. note:: | |
| 240 | ||
| 241 | This is a note. | |
| 242 | ||
| 243 | ||
| 244 | .. _typographical-conventions-see-also: | |
| 245 | ||
| 246 | See also | |
| 247 | -------- | |
| 248 | ||
| 249 | "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. | |
| 250 | ||
| 251 | .. seealso:: | |
| 252 | ||
| 253 | See :ref:`Quick Tutorial section on Requirements <qtut_requirements>`. | |
| 254 | ||
| 255 | ||
| 256 | .. _typographical-conventions-cross-references: | |
| 257 | ||
| 258 | Cross-references | |
| 259 | ---------------- | |
| 260 | ||
| 261 | Cross-references are links that may be to a document, arbitrary location, object, or other items. | |
| 262 | ||
| 263 | ||
| 264 | .. _typographical-conventions-cross-referencing-documents: | |
| 265 | ||
| 266 | Cross-referencing documents | |
| 267 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 268 | ||
| 269 | Links to pages within this documentation display as follows. | |
| 270 | ||
| 271 | :doc:`quick_tour` | |
| 272 | ||
| 273 | ||
| 274 | .. _typographical-conventions-cross-referencing-arbitrary-locations: | |
| 275 | ||
| 276 | Cross-referencing arbitrary locations | |
| 277 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 278 | ||
| 279 | Links to sections, and tables and figures with captions, within this documentation display as follows. | |
| 280 | ||
| 281 | :ref:`i18n_chapter` | |
| 282 | ||
| 283 | ||
| 284 | .. _typographical-conventions-cross-referencing-python: | |
| 285 | ||
| 286 | Python modules, classes, methods, and functions | |
| 287 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 288 | ||
| 289 | All of the following are clickable links to Python modules, classes, methods, and functions. | |
| 290 | ||
| 291 | Python module names display as follows. | |
| 292 | ||
| 293 | :mod:`pyramid.config` | |
| 294 | ||
| 295 | Python class names display as follows. | |
| 296 | ||
| 297 | :class:`pyramid.config.Configurator` | |
| 298 | ||
| 299 | Python method names display as follows. | |
| 300 | ||
| 301 | :meth:`pyramid.config.Configurator.add_view` | |
| 302 | ||
| 303 | Python function names display as follows. | |
| 304 | ||
| 305 | :func:`pyramid.renderers.render_to_response` | |
| 306 | ||
| 307 | Sometimes we show only the last segment of a Python object's name, which displays as follows. | |
| 308 | ||
| 309 | :func:`~pyramid.renderers.render_to_response` | |
| 310 | ||
| 311 | The application "Pyramid" itself displays as follows. | |
| 312 | ||
| 313 | :app:`Pyramid` | |
| 314 | ||
