rest25/documenting/markup.rst => rest262/documenting/markup.rst
3Additional Markup Constructs
4============================
5
6Sphinx adds a lot of new directives and interpreted text roles to standard reST
7markup.  This section contains the reference material for these facilities.
8Documentation for "standard" reST constructs is not included here, though
9they are used in the Python documentation.
10
n11-XXX: file-wide metadata
n11+.. note::
12+ 
13+   This is just an overview of Sphinx' extended markup capabilities; full
14+   coverage can be found in `its own documentation
15+   <http://sphinx.pocoo.org/contents.html>`_.
16+ 
12
13Meta-information markup
14-----------------------
15
16.. describe:: sectionauthor
17
18   Identifies the author of the current section.  The argument should include
19   the author's name such that it can be used for presentation (though it isn't)
56   platforms on which the module is available (if it is available on all
57   platforms, the option should be omitted).  The keys are short identifiers;
58   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
59   important to use a key which has already been used when applicable.
60
61   The ``synopsis`` option should consist of one sentence describing the
62   module's purpose -- it is currently only used in the Global Module Index.
63
n69+   The ``deprecated`` option can be given (with no value) to mark a module as
70+   deprecated; it will be designated as such in various locations then.
71+ 
64.. describe:: moduleauthor
65
66   The ``moduleauthor`` directive, which can appear multiple times, names the
67   authors of the module code, just like ``sectionauthor`` names the author(s)
68   of a piece of documentation.  It too does not result in any output currently.
n69- 
70
71.. note::
72
73   It is important to make the section title of a module-describing file
74   meaningful since that value will be inserted in the table-of-contents trees
75   in overview files.
76
77
184.. describe:: method
185
186   Describes an object method.  The parameters should not include the ``self``
187   parameter.  The description should include similar information to that
188   described for ``function``.
189
190.. describe:: opcode
191
n192-   Describes a Python bytecode instruction.
n199+   Describes a Python :term:`bytecode` instruction.
200+ 
201+.. describe:: cmdoption
202+ 
203+   Describes a command line option or switch.  Option argument names should be
204+   enclosed in angle brackets.  Example::
205+ 
206+      .. cmdoption:: -m <module>
207+ 
208+         Run a module as a script.
209+ 
210+.. describe:: envvar
211+ 
212+   Describes an environment variable that Python uses or defines.
193
194
195There is also a generic version of these directives:
196
197.. describe:: describe
198
199   This directive produces the same formatting as the specific ones explained
200   above but does not create index entries or cross-referencing targets.  It is
233* The highlighting language can be changed using the ``highlightlang``
234  directive, used as follows::
235
236     .. highlightlang:: c
237
238  This language is used until the next ``highlightlang`` directive is
239  encountered.
240
n241-* The valid values for the highlighting language are:
n261+* The values normally used for the highlighting language are:
242
243  * ``python`` (the default)
244  * ``c``
245  * ``rest``
246  * ``none`` (no highlighting)
247
248* If highlighting with the current language fails, the block is not highlighted
249  in any way.
250
251Longer displays of verbatim text may be included by storing the example text in
252an external file containing only plain text.  The file may be included using the
n253-standard ``include`` directive with the ``literal`` option flag.  For example,
n273+``literalinclude`` directive. [1]_ For example, to include the Python source file
254-to include the Python source file :file:`example.py`, use::
274+:file:`example.py`, use::
255
n256-   .. include:: example.py
n276+   .. literalinclude:: example.py
257-      :literal:
277+ 
278+The file name is relative to the current file's path.  Documentation-specific
279+include files should be placed in the ``Doc/includes`` subdirectory.
258
259
260Inline markup
261-------------
262
263As said before, Sphinx uses interpreted text roles to insert semantic markup in
264documents.
265
n266-The default role is ``var``, as that was one of the most common macros used in
n288+Names of local variables, such as function/method arguments, are an exception,
267-the old LaTeX docs.  That means that you can use ```var``` to refer to a
289+they should be marked simply with ``*var*``.
268-variable named "var".
269
270For all other roles, you have to write ``:rolename:`content```.
n292+ 
293+There are some additional facilities that make cross-referencing roles more
294+versatile:
295+ 
296+* You may supply an explicit title and reference target, like in reST direct
297+  hyperlinks: ``:role:`title <target>``` will refer to *target*, but the link
298+  text will be *title*.
299+ 
300+* If you prefix the content with ``!``, no reference/hyperlink will be created.
301+ 
302+* For the Python object roles, if you prefix the content with ``~``, the link
303+  text will only be the last component of the target.  For example,
304+  ``:meth:`~Queue.Queue.get``` will refer to ``Queue.Queue.get`` but only
305+  display ``get`` as the link text.
306+ 
307+  In HTML output, the link's ``title`` attribute (that is e.g. shown as a
308+  tool-tip on mouse-hover) will always be the full target name.
271
272The following roles refer to objects in modules and are possibly hyperlinked if
273a matching identifier is found:
274
275.. describe:: mod
276
277   The name of a module; a dotted name may be used.  This should also be used for
278   package names.
279
280.. describe:: func
281
282   The name of a Python function; dotted names may be used.  The role text
n283-   should include trailing parentheses to enhance readability.  The parentheses
n321+   should not include trailing parentheses to enhance readability.  The
284-   are stripped when searching for identifiers.
322+   parentheses are stripped when searching for identifiers.
285
286.. describe:: data
287
n288-   The name of a module-level variable.
n326+   The name of a module-level variable or constant.
289
290.. describe:: const
291
292   The name of a "defined" constant.  This may be a C-language ``#define``
293   or a Python variable that is not intended to be changed.
294
295.. describe:: class
296
297   A class name; a dotted name may be used.
298
299.. describe:: meth
300
301   The name of a method of an object.  The role text should include the type
n302-   name, method name and the trailing parentheses.  A dotted name may be used.
n340+   name and the method name.  A dotted name may be used.
303
304.. describe:: attr
305
306   The name of a data attribute of an object.
307
308.. describe:: exc
309
310   The name of an exception. A dotted name may be used.
311
312The name enclosed in this markup can include a module name and/or a class name.
313For example, ``:func:`filter``` could refer to a function named ``filter`` in
314the current module, or the built-in function of that name.  In contrast,
315``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
316module.
317
n356+Normally, names in these roles are searched first without any further
357+qualification, then with the current module name prepended, then with the
358+current module and class name (if any) prepended.  If you prefix the name with a
359+dot, this order is reversed.  For example, in the documentation of the
360+:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
361+while ``:func:`.open``` refers to :func:`codecs.open`.
362+ 
318A similar heuristic is used to determine whether the name is an attribute of
319the currently documented class.
320
321The following roles create cross-references to C-language constructs if they
322are defined in the API documentation:
323
324.. describe:: cdata
325
340
341The following role does possibly create a cross-reference, but does not refer
342to objects:
343
344.. describe:: token
345
346   The name of a grammar token (used in the reference manual to create links
347   between production displays).
n393+ 
394+ 
395+The following role creates a cross-reference to the term in the glossary:
396+ 
397+.. describe:: term
398+ 
399+   Reference to a term in the glossary.  The glossary is created using the
400+   ``glossary`` directive containing a definition list with terms and
401+   definitions.  It does not have to be in the same file as the ``term``
402+   markup, in fact, by default the Python docs have one global glossary
403+   in the ``glossary.rst`` file.
404+ 
405+   If you use a term that's not explained in a glossary, you'll get a warning
406+   during build.
348
349---------
350
351The following roles don't do anything special except formatting the text
352in a different style:
353
354.. describe:: command
355
390   conventions, the names of modifier keys should be spelled out, to improve
391   accessibility for new users and non-native speakers.  For example, an
392   *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
393   reference to a specific application or platform, the same sequence should be
394   marked as ``:kbd:`Control-x Control-f```.
395
396.. describe:: keyword
397
n398-   The name of a keyword in a programming language.
n457+   The name of a keyword in Python.
399
400.. describe:: mailheader
401
402   The name of an RFC 822-style mail header.  This markup does not imply that
403   the header is being used in an email message, but can be used to refer to any
404   header of the same "style."  This is also used for headers defined by the
405   various MIME specifications.  The header name should be entered in the same
406   way it would normally be found in practice, with the camel-casing conventions
451   The name of an executable program.  This may differ from the file name for
452   the executable for some platforms.  In particular, the ``.exe`` (or other)
453   extension should be omitted for Windows programs.
454
455.. describe:: regexp
456
457   A regular expression. Quotes should not be included.
458
n518+.. describe:: samp
519+ 
520+   A piece of literal text, such as code.  Within the contents, you can use
521+   curly braces to indicate a "variable" part, as in ``:file:``.
522+ 
523+   If you don't need the "variable part" indication, use the standard
524+   ````code```` instead.
525+ 
459.. describe:: var
460
461   A Python or C variable or parameter name.
462
463
464The following roles generate external links:
465
466.. describe:: pep
481
482
483.. _doc-ref-role:
484
485Cross-linking markup
486--------------------
487
488To support cross-referencing to arbitrary sections in the documentation, the
n489-standard reST labels are "abused" a bit:  Every label must precede a section
n556+standard reST labels are "abused" a bit: Every label must precede a section
490title; and every label name must be unique throughout the entire documentation
491source.
492
493You can then reference to these sections using the ``:ref:`label-name``` role.
494
495Example::
496
497   .. _my-reference-label:
540   should be placed at the top of the module section before any prose.
541
542   The first argument must be given and is the version in question; you can add
543   a second argument consisting of a *brief* explanation of the change.
544
545   Example::
546
547      .. versionadded:: 2.5
n548-         The `spam` parameter.
n615+         The *spam* parameter.
549
550   Note that there must be no blank line between the directive head and the
551   explanation; this is to make these blocks visually continuous in the markup.
552
553.. describe:: versionchanged
554
555   Similar to ``versionadded``, but describes when and what changed in the named
556   feature in some way (new parameters, changed side effects, etc.).
647mainly contained in information units, such as the language reference.
648
649The directive is ``index`` and contains one or more index entries.  Each entry
650consists of a type and a value, separated by a colon.
651
652For example::
653
654   .. index::
n655-      single: execution!context
n722+      single: executioncontext
656      module: __main__
657      module: sys
658      triple: module; search; path
659
660This directive contains five entries, which will be converted to entries in the
661generated index which link to the exact location of the index statement (or, in
662case of offline media, the corresponding page number).
663
664The possible entry types are:
665
666single
667   Creates a single index entry.  Can be made a subentry by separating the
n668-   subentry text with a semicolon (this is also used below to describe what
n735+   subentry text with a semicolon (this notation is also used below to describe
669-   entries are created).
736+   what entries are created).
670pair
671   ``pair: loop; statement`` is a shortcut that creates two index entries,
672   namely ``loop; statement`` and ``statement; loop``.
673triple
674   Likewise, ``triple: module; search; path`` is a shortcut that creates three
675   index entries, which are ``module; search path``, ``search; path, module`` and
n676-    ``path; module search``.
n743+   ``path; module search``.
677module, keyword, operator, object, exception, statement, builtin
678   These all create two index entries.  For example, ``module: hashlib`` creates
679   the entries ``module; hashlib`` and ``hashlib; module``.
n747+ 
748+For index directives containing only "single" entries, there is a shorthand
749+notation::
750+ 
751+   .. index:: BNF, grammar, syntax, notation
752+ 
753+This creates four index entries.
680
681
682Grammar production displays
683---------------------------
684
685Special markup is available for displaying the productions of a formal grammar.
686The markup is simple and does not attempt to model all aspects of BNF (or any
687derived forms), but provides enough to allow context-free grammars to be
694   given on a single line and consists of a name, separated by a colon from the
695   following definition.  If the definition spans multiple lines, each
696   continuation line must begin with a colon placed at the same column as in the
697   first line.
698
699   Blank lines are not allowed within ``productionlist`` directive arguments.
700
701   The definition can contain token names which are marked as interpreted text
n702-   (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references
n776+   (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references
703-   to the productions of these tokens.  Note that vertical bars used to indicate
777+   to the productions of these tokens.
704-   alternatives must be escaped with backslashes because otherwise they would
705-   indicate a substitution reference to the reST parser.
706
n779+   Note that no further reST parsing is done in the production, so that you
780+   don't have to escape ``*`` or ``|`` characters.
707
n782+ 
708-.. XXX describe optional first parameter 
783+.. XXX describe optional first parameter
709
710The following is an example taken from the Python Reference Manual::
711
712   .. productionlist::
n713-      try_stmt: try1_stmt \| try2_stmt
n788+      try_stmt: try1_stmt | try2_stmt
714-      try1_stmt: "try" ":" :token:`suite`
789+      try1_stmt: "try" ":" `suite`
715-               : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+
790+               : ("except" [`expression` ["," `target`]] ":" `suite`)+
716-               : ["else" ":" :token:`suite`]
791+               : ["else" ":" `suite`]
717-               : ["finally" ":" :token:`suite`]
792+               : ["finally" ":" `suite`]
718-      try2_stmt: "try" ":" :token:`suite`
793+      try2_stmt: "try" ":" `suite`
719-               : "finally" ":" :token:`suite`
794+               : "finally" ":" `suite`
720
721
722Substitutions
723-------------
724
725The documentation system provides three substitutions that are defined by default.
n726-They are set in the build configuration file, see :ref:`doc-build-config`.
n801+They are set in the build configuration file :file:`conf.py`.
727
728.. describe:: |release|
729
730   Replaced by the Python release the documentation refers to.  This is the full
731   version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
732
733.. describe:: |version|
734
735   Replaced by the Python version the documentation refers to. This consists
736   only of the major and minor version parts, e.g. ``2.5``, even for version
737   2.5.1.
738
739.. describe:: |today|
740
741   Replaced by either today's date, or the date set in the build configuration
742   file.  Normally has the format ``April 14, 2007``.
t818+ 
819+ 
820+.. rubric:: Footnotes
821+ 
822+.. [1] There is a standard ``.. include`` directive, but it raises errors if the
823+       file is not found.  This one only emits a warning.
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op