/Doc/documenting/markup.rst

Relevant Search: With Applications for Solr and Elasticsearch

For more in depth reading about search, ranking and generally everything you could ever want to know about how lucene, elasticsearch or solr work under the hood I highly suggest this book. Easily one of the most interesting technical books I have read in a long time. If you are tasked with solving search relevance problems even if not in Solr or Elasticsearch it should be your first reference. Amazon Affiliate Link

  1.. highlightlang:: rest
  2
  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
 11.. 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
 17
 18Meta-information markup
 19-----------------------
 20
 21.. describe:: sectionauthor
 22
 23   Identifies the author of the current section.  The argument should include
 24   the author's name such that it can be used for presentation (though it isn't)
 25   and email address.  The domain name portion of the address should be lower
 26   case.  Example::
 27
 28      .. sectionauthor:: Guido van Rossum <guido@python.org>
 29
 30   Currently, this markup isn't reflected in the output in any way, but it helps
 31   keep track of contributions.
 32
 33
 34Module-specific markup
 35----------------------
 36
 37The markup described in this section is used to provide information about a
 38module being documented.  Each module should be documented in its own file.
 39Normally this markup appears after the title heading of that file; a typical
 40file might start like this::
 41
 42   :mod:`parrot` -- Dead parrot access
 43   ===================================
 44
 45   .. module:: parrot
 46      :platform: Unix, Windows
 47      :synopsis: Analyze and reanimate dead parrots.
 48   .. moduleauthor:: Eric Cleese <eric@python.invalid>
 49   .. moduleauthor:: John Idle <john@python.invalid>
 50
 51As you can see, the module-specific markup consists of two directives, the
 52``module`` directive and the ``moduleauthor`` directive.
 53
 54.. describe:: module
 55
 56   This directive marks the beginning of the description of a module (or package
 57   submodule, in which case the name should be fully qualified, including the
 58   package name).
 59
 60   The ``platform`` option, if present, is a comma-separated list of the
 61   platforms on which the module is available (if it is available on all
 62   platforms, the option should be omitted).  The keys are short identifiers;
 63   examples that are in use include "IRIX", "Mac", "Windows", and "Unix".  It is
 64   important to use a key which has already been used when applicable.
 65
 66   The ``synopsis`` option should consist of one sentence describing the
 67   module's purpose -- it is currently only used in the Global Module Index.
 68
 69   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
 72.. describe:: moduleauthor
 73
 74   The ``moduleauthor`` directive, which can appear multiple times, names the
 75   authors of the module code, just like ``sectionauthor`` names the author(s)
 76   of a piece of documentation.  It too does not result in any output currently.
 77
 78.. note::
 79
 80   It is important to make the section title of a module-describing file
 81   meaningful since that value will be inserted in the table-of-contents trees
 82   in overview files.
 83
 84
 85Information units
 86-----------------
 87
 88There are a number of directives used to describe specific features provided by
 89modules.  Each directive requires one or more signatures to provide basic
 90information about what is being described, and the content should be the
 91description.  The basic version makes entries in the general index; if no index
 92entry is desired, you can give the directive option flag ``:noindex:``.  The
 93following example shows all of the features of this directive type::
 94
 95    .. function:: spam(eggs)
 96                  ham(eggs)
 97       :noindex:
 98
 99       Spam or ham the foo.
100
101The signatures of object methods or data attributes should always include the
102type name (``.. method:: FileInput.input(...)``), even if it is obvious from the
103context which type they belong to; this is to enable consistent
104cross-references.  If you describe methods belonging to an abstract protocol,
105such as "context managers", include a (pseudo-)type name too to make the
106index entries more informative.
107
108The directives are:
109
110.. describe:: cfunction
111
112   Describes a C function. The signature should be given as in C, e.g.::
113
114      .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
115
116   This is also used to describe function-like preprocessor macros.  The names
117   of the arguments should be given so they may be used in the description.
118
119   Note that you don't have to backslash-escape asterisks in the signature,
120   as it is not parsed by the reST inliner.
121
122.. describe:: cmember
123
124   Describes a C struct member. Example signature::
125
126      .. cmember:: PyObject* PyTypeObject.tp_bases
127
128   The text of the description should include the range of values allowed, how
129   the value should be interpreted, and whether the value can be changed.
130   References to structure members in text should use the ``member`` role.
131
132.. describe:: cmacro
133
134   Describes a "simple" C macro.  Simple macros are macros which are used
135   for code expansion, but which do not take arguments so cannot be described as
136   functions.  This is not to be used for simple constant definitions.  Examples
137   of its use in the Python documentation include :cmacro:`PyObject_HEAD` and
138   :cmacro:`Py_BEGIN_ALLOW_THREADS`.
139
140.. describe:: ctype
141
142   Describes a C type. The signature should just be the type name.
143
144.. describe:: cvar
145
146   Describes a global C variable.  The signature should include the type, such
147   as::
148
149      .. cvar:: PyObject* PyClass_Type
150
151.. describe:: data
152
153   Describes global data in a module, including both variables and values used
154   as "defined constants."  Class and object attributes are not documented
155   using this environment.
156
157.. describe:: exception
158
159   Describes an exception class.  The signature can, but need not include
160   parentheses with constructor arguments.
161
162.. describe:: function
163
164   Describes a module-level function.  The signature should include the
165   parameters, enclosing optional parameters in brackets.  Default values can be
166   given if it enhances clarity.  For example::
167
168      .. function:: Timer.repeat([repeat=3[, number=1000000]])
169
170   Object methods are not documented using this directive. Bound object methods
171   placed in the module namespace as part of the public interface of the module
172   are documented using this, as they are equivalent to normal functions for
173   most purposes.
174
175   The description should include information about the parameters required and
176   how they are used (especially whether mutable objects passed as parameters
177   are modified), side effects, and possible exceptions.  A small example may be
178   provided.
179
180.. describe:: class
181
182   Describes a class.  The signature can include parentheses with parameters
183   which will be shown as the constructor arguments.
184
185.. describe:: attribute
186
187   Describes an object data attribute.  The description should include
188   information about the type of the data to be expected and whether it may be
189   changed directly.
190
191.. describe:: method
192
193   Describes an object method.  The parameters should not include the ``self``
194   parameter.  The description should include similar information to that
195   described for ``function``.
196
197.. describe:: opcode
198
199   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.
213
214
215There is also a generic version of these directives:
216
217.. describe:: describe
218
219   This directive produces the same formatting as the specific ones explained
220   above but does not create index entries or cross-referencing targets.  It is
221   used, for example, to describe the directives in this document. Example::
222
223      .. describe:: opcode
224
225         Describes a Python bytecode instruction.
226
227
228Showing code examples
229---------------------
230
231Examples of Python source code or interactive sessions are represented using
232standard reST literal blocks.  They are started by a ``::`` at the end of the
233preceding paragraph and delimited by indentation.
234
235Representing an interactive session requires including the prompts and output
236along with the Python code.  No special markup is required for interactive
237sessions.  After the last line of input or output presented, there should not be
238an "unused" primary prompt; this is an example of what *not* to do::
239
240   >>> 1 + 1
241   2
242   >>>
243
244Syntax highlighting is handled in a smart way:
245
246* There is a "highlighting language" for each source file.  Per default,
247  this is ``'python'`` as the majority of files will have to highlight Python
248  snippets.
249
250* Within Python highlighting mode, interactive sessions are recognized
251  automatically and highlighted appropriately.
252
253* The highlighting language can be changed using the ``highlightlang``
254  directive, used as follows::
255
256     .. highlightlang:: c
257
258  This language is used until the next ``highlightlang`` directive is
259  encountered.
260
261* The values normally used for the highlighting language are:
262
263  * ``python`` (the default)
264  * ``c``
265  * ``rest``
266  * ``none`` (no highlighting)
267
268* If highlighting with the current language fails, the block is not highlighted
269  in any way.
270
271Longer displays of verbatim text may be included by storing the example text in
272an external file containing only plain text.  The file may be included using the
273``literalinclude`` directive. [1]_ For example, to include the Python source file
274:file:`example.py`, use::
275
276   .. literalinclude:: example.py
277
278The file name is relative to the current file's path.  Documentation-specific
279include files should be placed in the ``Doc/includes`` subdirectory.
280
281
282Inline markup
283-------------
284
285As said before, Sphinx uses interpreted text roles to insert semantic markup in
286documents.
287
288Names of local variables, such as function/method arguments, are an exception,
289they should be marked simply with ``*var*``.
290
291For all other roles, you have to write ``:rolename:`content```.
292
293There are some additional facilities that make cross-referencing roles more
294versatile:
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.
309
310The following roles refer to objects in modules and are possibly hyperlinked if
311a matching identifier is found:
312
313.. describe:: mod
314
315   The name of a module; a dotted name may be used.  This should also be used for
316   package names.
317
318.. describe:: func
319
320   The name of a Python function; dotted names may be used.  The role text
321   should not include trailing parentheses to enhance readability.  The
322   parentheses are stripped when searching for identifiers.
323
324.. describe:: data
325
326   The name of a module-level variable or constant.
327
328.. describe:: const
329
330   The name of a "defined" constant.  This may be a C-language ``#define``
331   or a Python variable that is not intended to be changed.
332
333.. describe:: class
334
335   A class name; a dotted name may be used.
336
337.. describe:: meth
338
339   The name of a method of an object.  The role text should include the type
340   name and the method name.  A dotted name may be used.
341
342.. describe:: attr
343
344   The name of a data attribute of an object.
345
346.. describe:: exc
347
348   The name of an exception. A dotted name may be used.
349
350The name enclosed in this markup can include a module name and/or a class name.
351For example, ``:func:`filter``` could refer to a function named ``filter`` in
352the current module, or the built-in function of that name.  In contrast,
353``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo``
354module.
355
356Normally, names in these roles are searched first without any further
357qualification, then with the current module name prepended, then with the
358current module and class name (if any) prepended.  If you prefix the name with a
359dot, this order is reversed.  For example, in the documentation of the
360:mod:`codecs` module, ``:func:`open``` always refers to the built-in function,
361while ``:func:`.open``` refers to :func:`codecs.open`.
362
363A similar heuristic is used to determine whether the name is an attribute of
364the currently documented class.
365
366The following roles create cross-references to C-language constructs if they
367are defined in the API documentation:
368
369.. describe:: cdata
370
371   The name of a C-language variable.
372
373.. describe:: cfunc
374
375   The name of a C-language function. Should include trailing parentheses.
376
377.. describe:: cmacro
378
379   The name of a "simple" C macro, as defined above.
380
381.. describe:: ctype
382
383   The name of a C-language type.
384
385
386The following role does possibly create a cross-reference, but does not refer
387to objects:
388
389.. describe:: token
390
391   The name of a grammar token (used in the reference manual to create links
392   between production displays).
393
394
395The 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.
407
408---------
409
410The following roles don't do anything special except formatting the text
411in a different style:
412
413.. describe:: command
414
415   The name of an OS-level command, such as ``rm``.
416
417.. describe:: dfn
418
419   Mark the defining instance of a term in the text.  (No index entries are
420   generated.)
421
422.. describe:: envvar
423
424   An environment variable.  Index entries are generated.
425
426.. describe:: file
427
428   The name of a file or directory.  Within the contents, you can use curly
429   braces to indicate a "variable" part, for example::
430
431      ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
432
433   In the built documentation, the ``x`` will be displayed differently to
434   indicate that it is to be replaced by the Python minor version.
435
436.. describe:: guilabel
437
438   Labels presented as part of an interactive user interface should be marked
439   using ``guilabel``.  This includes labels from text-based interfaces such as
440   those created using :mod:`curses` or other text-based libraries.  Any label
441   used in the interface should be marked with this role, including button
442   labels, window titles, field names, menu and menu selection names, and even
443   values in selection lists.
444
445.. describe:: kbd
446
447   Mark a sequence of keystrokes.  What form the key sequence takes may depend
448   on platform- or application-specific conventions.  When there are no relevant
449   conventions, the names of modifier keys should be spelled out, to improve
450   accessibility for new users and non-native speakers.  For example, an
451   *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without
452   reference to a specific application or platform, the same sequence should be
453   marked as ``:kbd:`Control-x Control-f```.
454
455.. describe:: keyword
456
457   The name of a keyword in Python.
458
459.. describe:: mailheader
460
461   The name of an RFC 822-style mail header.  This markup does not imply that
462   the header is being used in an email message, but can be used to refer to any
463   header of the same "style."  This is also used for headers defined by the
464   various MIME specifications.  The header name should be entered in the same
465   way it would normally be found in practice, with the camel-casing conventions
466   being preferred where there is more than one common usage. For example:
467   ``:mailheader:`Content-Type```.
468
469.. describe:: makevar
470
471   The name of a :command:`make` variable.
472
473.. describe:: manpage
474
475   A reference to a Unix manual page including the section,
476   e.g. ``:manpage:`ls(1)```.
477
478.. describe:: menuselection
479
480   Menu selections should be marked using the ``menuselection`` role.  This is
481   used to mark a complete sequence of menu selections, including selecting
482   submenus and choosing a specific operation, or any subsequence of such a
483   sequence.  The names of individual selections should be separated by
484   ``-->``.
485
486   For example, to mark the selection "Start > Programs", use this markup::
487
488      :menuselection:`Start --> Programs`
489
490   When including a selection that includes some trailing indicator, such as the
491   ellipsis some operating systems use to indicate that the command opens a
492   dialog, the indicator should be omitted from the selection name.
493
494.. describe:: mimetype
495
496   The name of a MIME type, or a component of a MIME type (the major or minor
497   portion, taken alone).
498
499.. describe:: newsgroup
500
501   The name of a Usenet newsgroup.
502
503.. describe:: option
504
505   A command-line option to an executable program.  The leading hyphen(s) must
506   be included.
507
508.. describe:: program
509
510   The name of an executable program.  This may differ from the file name for
511   the executable for some platforms.  In particular, the ``.exe`` (or other)
512   extension should be omitted for Windows programs.
513
514.. describe:: regexp
515
516   A regular expression. Quotes should not be included.
517
518.. 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
526.. describe:: var
527
528   A Python or C variable or parameter name.
529
530
531The following roles generate external links:
532
533.. describe:: pep
534
535   A reference to a Python Enhancement Proposal.  This generates appropriate
536   index entries. The text "PEP *number*\ " is generated; in the HTML output,
537   this text is a hyperlink to an online copy of the specified PEP.
538
539.. describe:: rfc
540
541   A reference to an Internet Request for Comments.  This generates appropriate
542   index entries. The text "RFC *number*\ " is generated; in the HTML output,
543   this text is a hyperlink to an online copy of the specified RFC.
544
545
546Note that there are no special roles for including hyperlinks as you can use
547the standard reST markup for that purpose.
548
549
550.. _doc-ref-role:
551
552Cross-linking markup
553--------------------
554
555To support cross-referencing to arbitrary sections in the documentation, the
556standard reST labels are "abused" a bit: Every label must precede a section
557title; and every label name must be unique throughout the entire documentation
558source.
559
560You can then reference to these sections using the ``:ref:`label-name``` role.
561
562Example::
563
564   .. _my-reference-label:
565
566   Section to cross-reference
567   --------------------------
568
569   This is the text of the section.
570
571   It refers to the section itself, see :ref:`my-reference-label`.
572
573The ``:ref:`` invocation is replaced with the section title.
574
575
576Paragraph-level markup
577----------------------
578
579These directives create short paragraphs and can be used inside information
580units as well as normal text:
581
582.. describe:: note
583
584   An especially important bit of information about an API that a user should be
585   aware of when using whatever bit of API the note pertains to.  The content of
586   the directive should be written in complete sentences and include all
587   appropriate punctuation.
588
589   Example::
590
591      .. note::
592
593         This function is not suitable for sending spam e-mails.
594
595.. describe:: warning
596
597   An important bit of information about an API that a user should be aware of
598   when using whatever bit of API the warning pertains to.  The content of the
599   directive should be written in complete sentences and include all appropriate
600   punctuation.  This should only be chosen over ``note`` for information
601   regarding the possibility of crashes, data loss, or security implications.
602
603.. describe:: versionadded
604
605   This directive documents the version of Python which added the described
606   feature to the library or C API. When this applies to an entire module, it
607   should be placed at the top of the module section before any prose.
608
609   The first argument must be given and is the version in question; you can add
610   a second argument consisting of a *brief* explanation of the change.
611
612   Example::
613
614      .. versionadded:: 2.5
615         The *spam* parameter.
616
617   Note that there must be no blank line between the directive head and the
618   explanation; this is to make these blocks visually continuous in the markup.
619
620.. describe:: versionchanged
621
622   Similar to ``versionadded``, but describes when and what changed in the named
623   feature in some way (new parameters, changed side effects, etc.).
624
625--------------
626
627.. describe:: seealso
628
629   Many sections include a list of references to module documentation or
630   external documents.  These lists are created using the ``seealso`` directive.
631
632   The ``seealso`` directive is typically placed in a section just before any
633   sub-sections.  For the HTML output, it is shown boxed off from the main flow
634   of the text.
635
636   The content of the ``seealso`` directive should be a reST definition list.
637   Example::
638
639      .. seealso::
640
641         Module :mod:`zipfile`
642            Documentation of the :mod:`zipfile` standard module.
643
644         `GNU tar manual, Basic Tar Format <http://link>`_
645            Documentation for tar archive files, including GNU tar extensions.
646
647.. describe:: rubric
648
649   This directive creates a paragraph heading that is not used to create a
650   table of contents node.  It is currently used for the "Footnotes" caption.
651
652.. describe:: centered
653
654   This directive creates a centered boldfaced paragraph.  Use it as follows::
655
656      .. centered::
657
658         Paragraph contents.
659
660
661Table-of-contents markup
662------------------------
663
664Since reST does not have facilities to interconnect several documents, or split
665documents into multiple output files, Sphinx uses a custom directive to add
666relations between the single files the documentation is made of, as well as
667tables of contents.  The ``toctree`` directive is the central element.
668
669.. describe:: toctree
670
671   This directive inserts a "TOC tree" at the current location, using the
672   individual TOCs (including "sub-TOC trees") of the files given in the
673   directive body.  A numeric ``maxdepth`` option may be given to indicate the
674   depth of the tree; by default, all levels are included.
675
676   Consider this example (taken from the library reference index)::
677
678      .. toctree::
679         :maxdepth: 2
680
681         intro.rst
682         strings.rst
683         datatypes.rst
684         numeric.rst
685         (many more files listed here)
686
687   This accomplishes two things:
688
689   * Tables of contents from all those files are inserted, with a maximum depth
690     of two, that means one nested heading.  ``toctree`` directives in those
691     files are also taken into account.
692   * Sphinx knows that the relative order of the files ``intro.rst``,
693     ``strings.rst`` and so forth, and it knows that they are children of the
694     shown file, the library index.  From this information it generates "next
695     chapter", "previous chapter" and "parent chapter" links.
696
697   In the end, all files included in the build process must occur in one
698   ``toctree`` directive; Sphinx will emit a warning if it finds a file that is
699   not included, because that means that this file will not be reachable through
700   standard navigation.
701
702   The special file ``contents.rst`` at the root of the source directory is the
703   "root" of the TOC tree hierarchy; from it the "Contents" page is generated.
704
705
706Index-generating markup
707-----------------------
708
709Sphinx automatically creates index entries from all information units (like
710functions, classes or attributes) like discussed before.
711
712However, there is also an explicit directive available, to make the index more
713comprehensive and enable index entries in documents where information is not
714mainly contained in information units, such as the language reference.
715
716The directive is ``index`` and contains one or more index entries.  Each entry
717consists of a type and a value, separated by a colon.
718
719For example::
720
721   .. index::
722      single: execution; context
723      module: __main__
724      module: sys
725      triple: module; search; path
726
727This directive contains five entries, which will be converted to entries in the
728generated index which link to the exact location of the index statement (or, in
729case of offline media, the corresponding page number).
730
731The possible entry types are:
732
733single
734   Creates a single index entry.  Can be made a subentry by separating the
735   subentry text with a semicolon (this notation is also used below to describe
736   what entries are created).
737pair
738   ``pair: loop; statement`` is a shortcut that creates two index entries,
739   namely ``loop; statement`` and ``statement; loop``.
740triple
741   Likewise, ``triple: module; search; path`` is a shortcut that creates three
742   index entries, which are ``module; search path``, ``search; path, module`` and
743   ``path; module search``.
744module, keyword, operator, object, exception, statement, builtin
745   These all create two index entries.  For example, ``module: hashlib`` creates
746   the entries ``module; hashlib`` and ``hashlib; module``.
747
748For index directives containing only "single" entries, there is a shorthand
749notation::
750
751   .. index:: BNF, grammar, syntax, notation
752
753This creates four index entries.
754
755
756Grammar production displays
757---------------------------
758
759Special markup is available for displaying the productions of a formal grammar.
760The markup is simple and does not attempt to model all aspects of BNF (or any
761derived forms), but provides enough to allow context-free grammars to be
762displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
763the definition of the symbol.  There is this directive:
764
765.. describe:: productionlist
766
767   This directive is used to enclose a group of productions.  Each production is
768   given on a single line and consists of a name, separated by a colon from the
769   following definition.  If the definition spans multiple lines, each
770   continuation line must begin with a colon placed at the same column as in the
771   first line.
772
773   Blank lines are not allowed within ``productionlist`` directive arguments.
774
775   The definition can contain token names which are marked as interpreted text
776   (e.g. ``unaryneg ::= "-" `integer```) -- this generates cross-references
777   to the productions of these tokens.
778
779   Note that no further reST parsing is done in the production, so that you
780   don't have to escape ``*`` or ``|`` characters.
781
782
783.. XXX describe optional first parameter
784
785The following is an example taken from the Python Reference Manual::
786
787   .. productionlist::
788      try_stmt: try1_stmt | try2_stmt
789      try1_stmt: "try" ":" `suite`
790               : ("except" [`expression` ["," `target`]] ":" `suite`)+
791               : ["else" ":" `suite`]
792               : ["finally" ":" `suite`]
793      try2_stmt: "try" ":" `suite`
794               : "finally" ":" `suite`
795
796
797Substitutions
798-------------
799
800The documentation system provides three substitutions that are defined by default.
801They are set in the build configuration file :file:`conf.py`.
802
803.. describe:: |release|
804
805   Replaced by the Python release the documentation refers to.  This is the full
806   version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``.
807
808.. describe:: |version|
809
810   Replaced by the Python version the documentation refers to. This consists
811   only of the major and minor version parts, e.g. ``2.5``, even for version
812   2.5.1.
813
814.. describe:: |today|
815
816   Replaced by either today's date, or the date set in the build configuration
817   file.  Normally has the format ``April 14, 2007``.
818
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.