summaryrefslogtreecommitdiffstats
path: root/doc/usage/restructuredtext/directives.rst
blob: ff425246fa03c3d4ab6b3eac16b4d13d1b67b20b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
.. highlight:: rst

==========
Directives
==========

:ref:`As previously discussed <rst-directives>`, a directive is a generic block
of explicit markup. While Docutils provides a number of directives, Sphinx
provides many more and uses directives as one of the primary extension
mechanisms.

See :doc:`/usage/domains/index` for roles added by domains.

.. seealso::

   Refer to the :ref:`reStructuredText Primer <rst-directives>` for an overview
   of the directives provided by Docutils.


.. _toctree-directive:

Table of contents
-----------------

.. index:: pair: table of; contents

Since reST does not have facilities to interconnect several documents, or split
documents into multiple output files, Sphinx uses a custom directive to add
relations between the single files the documentation is made of, as well as
tables of contents.  The ``toctree`` directive is the central element.

.. note::

   Simple "inclusion" of one file in another can be done with the
   :dudir:`include` directive.

.. note::

   To create table of contents for current document (.rst file), use the
   standard reST :dudir:`contents directive <table-of-contents>`.

.. rst:directive:: toctree

   This directive inserts a "TOC tree" at the current location, using the
   individual TOCs (including "sub-TOC trees") of the documents given in the
   directive body.  Relative document names (not beginning with a slash) are
   relative to the document the directive occurs in, absolute names are relative
   to the source directory.  A numeric ``maxdepth`` option may be given to
   indicate the depth of the tree; by default, all levels are included. [#]_

   The representation of "TOC tree" is changed in each output format.  The
   builders that output multiple files (ex. HTML) treat it as a collection of
   hyperlinks.  On the other hand, the builders that output a single file (ex.
   LaTeX, man page, etc.) replace it with the content of the documents on the
   TOC tree.

   Consider this example (taken from the Python docs' library reference index)::

      .. toctree::
         :maxdepth: 2

         intro
         strings
         datatypes
         numeric
         (many more documents listed here)

   This accomplishes two things:

   * Tables of contents from all those documents are inserted, with a maximum
     depth of two, that means one nested heading.  ``toctree`` directives in
     those documents are also taken into account.
   * Sphinx knows the relative order of the documents ``intro``,
     ``strings`` and so forth, and it knows that they are children of the shown
     document, the library index.  From this information it generates "next
     chapter", "previous chapter" and "parent chapter" links.

   **Entries**

   Document titles in the :rst:dir:`toctree` will be automatically read from the
   title of the referenced document. If that isn't what you want, you can
   specify an explicit title and target using a similar syntax to reST
   hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This
   looks like::

       .. toctree::

          intro
          All about strings <strings>
          datatypes

   The second line above will link to the ``strings`` document, but will use the
   title "All about strings" instead of the title of the ``strings`` document.

   You can also add external links, by giving an HTTP URL instead of a document
   name.

   **Section numbering**

   If you want to have section numbers even in HTML output, give the
   **toplevel** toctree a ``numbered`` option.  For example::

      .. toctree::
         :numbered:

         foo
         bar

   Numbering then starts at the heading of ``foo``.  Sub-toctrees are
   automatically numbered (don't give the ``numbered`` flag to those).

   Numbering up to a specific depth is also possible, by giving the depth as a
   numeric argument to ``numbered``.

   **Additional options**

   You can use the ``caption`` option to provide a toctree caption and you can
   use the ``name`` option to provide an implicit target name that can be
   referenced by using :rst:role:`ref`::

      .. toctree::
         :caption: Table of Contents
         :name: mastertoc

         foo

   If you want only the titles of documents in the tree to show up, not other
   headings of the same level, you can use the ``titlesonly`` option::

      .. toctree::
         :titlesonly:

         foo
         bar

   You can use "globbing" in toctree directives, by giving the ``glob`` flag
   option.  All entries are then matched against the list of available
   documents, and matches are inserted into the list alphabetically.  Example::

      .. toctree::
         :glob:

         intro*
         recipe/*
         *

   This includes first all documents whose names start with ``intro``, then all
   documents in the ``recipe`` folder, then all remaining documents (except the
   one containing the directive, of course.) [#]_

   The special entry name ``self`` stands for the document containing the
   toctree directive.  This is useful if you want to generate a "sitemap" from
   the toctree.

   You can use the ``reversed`` flag option to reverse the order of the entries
   in the list. This can be useful when using the ``glob`` flag option to
   reverse the ordering of the files.  Example::

      .. toctree::
         :glob:
         :reversed:

         recipe/*

   You can also give a "hidden" option to the directive, like this::

      .. toctree::
         :hidden:

         doc_1
         doc_2

   This will still notify Sphinx of the document hierarchy, but not insert links
   into the document at the location of the directive -- this makes sense if you
   intend to insert these links yourself, in a different style, or in the HTML
   sidebar.

   In cases where you want to have only one top-level toctree and hide all other
   lower level toctrees you can add the "includehidden" option to the top-level
   toctree entry::

      .. toctree::
         :includehidden:

         doc_1
         doc_2

   All other toctree entries can then be eliminated by the "hidden" option.

   In the end, all documents in the :term:`source directory` (or subdirectories)
   must occur in some ``toctree`` directive; Sphinx will emit a warning if it
   finds a file that is not included, because that means that this file will not
   be reachable through standard navigation.

   Use :confval:`exclude_patterns` to explicitly exclude documents or
   directories from building completely.  Use :ref:`the "orphan" metadata
   <metadata>` to let a document be built, but notify Sphinx that it is not
   reachable via a toctree.

   The "root document" (selected by :confval:`root_doc`) is the "root" of the TOC
   tree hierarchy.  It can be used as the documentation's main page, or as a
   "full table of contents" if you don't give a ``maxdepth`` option.

   .. versionchanged:: 0.3
      Added "globbing" option.

   .. versionchanged:: 0.6
      Added "numbered" and "hidden" options as well as external links and
      support for "self" references.

   .. versionchanged:: 1.0
      Added "titlesonly" option.

   .. versionchanged:: 1.1
      Added numeric argument to "numbered".

   .. versionchanged:: 1.2
      Added "includehidden" option.

   .. versionchanged:: 1.3
      Added "caption" and "name" option.

Special names
^^^^^^^^^^^^^

Sphinx reserves some document names for its own use; you should not try to
create documents with these names -- it will cause problems.

The special document names (and pages generated for them) are:

* ``genindex``, ``modindex``, ``search``

  These are used for the general index, the Python module index, and the search
  page, respectively.

  The general index is populated with entries from modules, all
  index-generating :ref:`object descriptions <basic-domain-markup>`, and from
  :rst:dir:`index` directives.

  The Python module index contains one entry per :rst:dir:`py:module`
  directive.

  The search page contains a form that uses the generated JSON search index and
  JavaScript to full-text search the generated documents for search words; it
  should work on every major browser that supports modern JavaScript.

* every name beginning with ``_``

  Though few such names are currently used by Sphinx, you should not
  create documents or document-containing directories with such names.  (Using
  ``_`` as a prefix for a custom template directory is fine.)

.. warning::

   Be careful with unusual characters in filenames.  Some formats may interpret
   these characters in unexpected ways:

   * Do not use the colon ``:`` for HTML based formats.  Links to other parts
     may not work.

   * Do not use the plus ``+`` for the ePub format.  Some resources may not be
     found.


Paragraph-level markup
----------------------

.. index:: note, warning
           pair: changes; in version

These directives create short paragraphs and can be used inside information
units as well as normal text.

.. rst:directive:: .. note::

   An especially important bit of information about an API that a user should be
   aware of when using whatever bit of API the note pertains to.  The content of
   the directive should be written in complete sentences and include all
   appropriate punctuation.

   Example::

      .. note::

         This function is not suitable for sending spam e-mails.

.. rst:directive:: .. warning::

   An important bit of information about an API that a user should be very aware
   of when using whatever bit of API the warning pertains to.  The content of
   the directive should be written in complete sentences and include all
   appropriate punctuation. This differs from :rst:dir:`note` in that it is
   recommended over :rst:dir:`note` for information regarding security.

.. rst:directive:: .. versionadded:: version

   This directive documents the version of the project which added the described
   feature to the library or C API. When this applies to an entire module, it
   should be placed at the top of the module section before any prose.

   The first argument must be given and is the version in question; you can add
   a second argument consisting of a *brief* explanation of the change.

   Example::

      .. versionadded:: 2.5
         The *spam* parameter.

   Note that there must be no blank line between the directive head and the
   explanation; this is to make these blocks visually continuous in the markup.

.. rst:directive:: .. versionchanged:: version

   Similar to :rst:dir:`versionadded`, but describes when and what changed in
   the named feature in some way (new parameters, changed side effects, etc.).

.. rst:directive:: .. deprecated:: version

   Similar to :rst:dir:`versionchanged`, but describes when the feature was
   deprecated.  An explanation can also be given, for example to inform the
   reader what should be used instead.  Example::

      .. deprecated:: 3.1
         Use :func:`spam` instead.

.. rst:directive:: .. versionremoved:: version

   Similar to :rst:dir:`versionadded`, but describes when the feature was removed.
   An explanation may be provided to inform the reader what to use instead,
   or why the feature was removed.
   Example::

      .. versionremoved:: 4.0
         The :func:`spam` function is more flexible, and should be used instead.

   .. versionadded:: 7.3

.. rst:directive:: seealso

   Many sections include a list of references to module documentation or
   external documents.  These lists are created using the :rst:dir:`seealso`
   directive.

   The :rst:dir:`seealso` directive is typically placed in a section just before
   any subsections.  For the HTML output, it is shown boxed off from the main
   flow of the text.

   The content of the :rst:dir:`seealso` directive should be a reST definition
   list. Example::

      .. seealso::

         Module :py:mod:`zipfile`
            Documentation of the :py:mod:`zipfile` standard module.

         `GNU tar manual, Basic Tar Format <https://link>`_
            Documentation for tar archive files, including GNU tar extensions.

   There's also a "short form" allowed that looks like this::

      .. seealso:: modules :py:mod:`zipfile`, :py:mod:`tarfile`

   .. versionadded:: 0.5
      The short form.

.. rst:directive:: .. rubric:: title

   This directive creates a paragraph heading that is not used to create a
   table of contents node.

   .. note::

      If the *title* of the rubric is "Footnotes" (or the selected language's
      equivalent), this rubric is ignored by the LaTeX writer, since it is
      assumed to only contain footnote definitions and therefore would create an
      empty heading.

.. rst:directive:: centered

   This directive creates a centered boldfaced line of text.  Use it as
   follows::

      .. centered:: LICENSE AGREEMENT

   .. deprecated:: 1.1
      This presentation-only directive is a legacy from older versions.
      Use a :ref:`rst-class <rstclass>` directive instead and add an
      appropriate style.

.. rst:directive:: hlist

   This directive must contain a bullet list.  It will transform it into a more
   compact list by either distributing more than one item horizontally, or
   reducing spacing between items, depending on the builder.

   For builders that support the horizontal distribution, there is a ``columns``
   option that specifies the number of columns; it defaults to 2.  Example::

      .. hlist::
         :columns: 3

         * A list of
         * short items
         * that should be
         * displayed
         * horizontally

   .. versionadded:: 0.6


.. _code-examples:

Showing code examples
---------------------

.. index:: pair: code; examples
           single: sourcecode

There are multiple ways to show syntax-highlighted literal code blocks in
Sphinx:

* using :ref:`reST doctest blocks <rst-doctest-blocks>`;
* using :ref:`reST literal blocks <rst-literal-blocks>`, optionally in
  combination with the :rst:dir:`highlight` directive;
* using the :rst:dir:`code-block` directive;
* and using the :rst:dir:`literalinclude` directive.

Doctest blocks can only be used
to show interactive Python sessions, while the remaining three can be used for
other languages. Of these three, literal blocks are useful when an entire
document, or at least large sections of it, use code blocks with the same
syntax and which should be styled in the same manner. On the other hand, the
:rst:dir:`code-block` directive makes more sense when you want more fine-tuned
control over the styling of each block or when you have a document containing
code blocks using multiple varied syntaxes. Finally, the
:rst:dir:`literalinclude` directive is useful for including entire code files
in your documentation.

In all cases, Syntax highlighting is provided by `Pygments
<https://pygments.org>`_. When using literal blocks, this is configured using
any :rst:dir:`highlight` directives in the source file. When a ``highlight``
directive is encountered, it is used until the next ``highlight`` directive is
encountered. If there is no ``highlight`` directive in the file, the global
highlighting language is used. This defaults to ``python`` but can be
configured using the :confval:`highlight_language` config value. The following
values are supported:

* ``none`` (no highlighting)
* ``default`` (similar to ``python3`` but with a fallback to ``none`` without
  warning highlighting fails; the default when :confval:`highlight_language`
  isn't set)
* ``guess`` (let Pygments guess the lexer based on contents, only works with
  certain well-recognizable languages)
* ``python``
* ``rest``
* ``c``
* ... and any other `lexer alias that Pygments supports`__

If highlighting with the selected language fails (i.e. Pygments emits an
"Error" token), the block is not highlighted in any way.

.. important::

   The list of lexer aliases supported is tied to the Pygment version. If you
   want to ensure consistent highlighting, you should fix your version of
   Pygments.

__ https://pygments.org/docs/lexers

.. rst:directive:: .. highlight:: language

   Example::

      .. highlight:: c

   This language is used until the next ``highlight`` directive is encountered.
   As discussed previously, *language* can be any lexer alias supported by
   Pygments.

   .. rubric:: options

   .. rst:directive:option:: linenothreshold: threshold
      :type: number (optional)

      Enable to generate line numbers for code blocks.

      This option takes an optional number as threshold parameter.  If any
      threshold given, the directive will produce line numbers only for the code
      blocks longer than N lines.  If not given, line numbers will be produced
      for all of code blocks.

      Example::

         .. highlight:: python
            :linenothreshold: 5

   .. rst:directive:option:: force
      :type: no value

      If given, minor errors on highlighting are ignored.

      .. versionadded:: 2.1

.. rst:directive:: .. code-block:: [language]
                   .. sourcecode:: [language]

   Example::

      .. code-block:: ruby

         Some Ruby code.

   The directive's alias name :rst:dir:`sourcecode` works as well.  This
   directive takes a language name as an argument.  It can be `any lexer alias
   supported by Pygments <https://pygments.org/docs/lexers/>`_.  If it is not
   given, the setting of :rst:dir:`highlight` directive will be used.  If not
   set, :confval:`highlight_language` will be used.  To display a code example
   *inline* within other text, rather than as a separate block, you can use the
   :rst:role:`code` role instead.

   .. versionchanged:: 2.0
      The ``language`` argument becomes optional.

   .. rubric:: options

   .. rst:directive:option:: linenos
      :type: no value

      Enable to generate line numbers for the code block::

         .. code-block:: ruby
            :linenos:

            Some more Ruby code.

   .. rst:directive:option:: lineno-start: number
      :type: number

      Set the first line number of the code block.  If present, ``linenos``
      option is also automatically activated::

         .. code-block:: ruby
            :lineno-start: 10

            Some more Ruby code, with line numbering starting at 10.

      .. versionadded:: 1.3

   .. rst:directive:option:: emphasize-lines: line numbers
      :type: comma separated numbers

      Emphasize particular lines of the code block::

       .. code-block:: python
          :emphasize-lines: 3,5

          def some_function():
              interesting = False
              print('This line is highlighted.')
              print('This one is not...')
              print('...but this one is.')

      .. versionadded:: 1.1
      .. versionchanged:: 1.6.6
         LaTeX supports the ``emphasize-lines`` option.

   .. rst:directive:option: force
      :type: no value

      Ignore minor errors on highlighting

      .. versionchanged:: 2.1

   .. rst:directive:option:: caption: caption of code block
      :type: text

      Set a caption to the code block.

      .. versionadded:: 1.3

   .. rst:directive:option:: name: a label for hyperlink
      :type: text

      Define implicit target name that can be referenced by using
      :rst:role:`ref`.  For example::

        .. code-block:: python
           :caption: this.py
           :name: this-py

           print('Explicit is better than implicit.')

      In order to cross-reference a code-block using either the
      :rst:role:`ref` or the :rst:role:`numref` role, it is necessary
      that both :strong:`name` and :strong:`caption` be defined. The
      argument of :strong:`name` can then be given to :rst:role:`numref`
      to generate the cross-reference. Example::

        See :numref:`this-py` for an example.

      When using :rst:role:`ref`, it is possible to generate a cross-reference
      with only :strong:`name` defined, provided an explicit title is
      given. Example::

        See :ref:`this code snippet <this-py>` for an example.

      .. versionadded:: 1.3

   .. rst:directive:option:: class: class names
      :type: a list of class names separated by spaces

      The class name of the graph.

      .. versionadded:: 1.4

   .. rst:directive:option:: dedent: number
      :type: number or no value

      Strip indentation characters from the code block.  When number given,
      leading N characters are removed.  When no argument given, leading spaces
      are removed via :func:`textwrap.dedent()`.  For example::

         .. code-block:: ruby
            :linenos:
            :dedent: 4

                some ruby code

      .. versionadded:: 1.3
      .. versionchanged:: 3.5
         Support automatic dedent.

   .. rst:directive:option:: force
      :type: no value

      If given, minor errors on highlighting are ignored.

      .. versionadded:: 2.1

.. rst:directive:: .. literalinclude:: filename

   Longer displays of verbatim text may be included by storing the example text
   in an external file containing only plain text.  The file may be included
   using the ``literalinclude`` directive. [#]_ For example, to include the
   Python source file :file:`example.py`, use::

      .. literalinclude:: example.py

   The file name is usually relative to the current file's path.  However, if
   it is absolute (starting with ``/``), it is relative to the top source
   directory.

   **Additional options**

   Like :rst:dir:`code-block`, the directive supports the ``linenos`` flag
   option to switch on line numbers, the ``lineno-start`` option to select the
   first line number, the ``emphasize-lines`` option to emphasize particular
   lines, the ``name`` option to provide an implicit target name, the
   ``dedent`` option to strip indentation characters for the code block, and a
   ``language`` option to select a language different from the current file's
   standard language. In addition, it supports the ``caption`` option; however,
   this can be provided with no argument to use the filename as the caption.
   Example with options::

      .. literalinclude:: example.rb
         :language: ruby
         :emphasize-lines: 12,15-18
         :linenos:

   Tabs in the input are expanded if you give a ``tab-width`` option with the
   desired tab width.

   Include files are assumed to be encoded in the :confval:`source_encoding`.
   If the file has a different encoding, you can specify it with the
   ``encoding`` option::

      .. literalinclude:: example.py
         :encoding: latin-1

   The directive also supports including only parts of the file.  If it is a
   Python module, you can select a class, function or method to include using
   the ``pyobject`` option::

      .. literalinclude:: example.py
         :pyobject: Timer.start

   This would only include the code lines belonging to the ``start()`` method
   in the ``Timer`` class within the file.

   Alternately, you can specify exactly which lines to include by giving a
   ``lines`` option::

      .. literalinclude:: example.py
         :lines: 1,3,5-10,20-

   This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.

   Another way to control which part of the file is included is to use the
   ``start-after`` and ``end-before`` options (or only one of them).  If
   ``start-after`` is given as a string option, only lines that follow the
   first line containing that string are included.  If ``end-before`` is given
   as a string option, only lines that precede the first lines containing that
   string are included. The ``start-at`` and ``end-at`` options behave in a
   similar way, but the lines containing the matched string are included.

   ``start-after``/``start-at`` and ``end-before``/``end-at`` can have same string.
   ``start-after``/``start-at`` filter lines before the line that contains
   option string (``start-at`` will keep the line). Then ``end-before``/``end-at``
   filter lines after the line that contains option string (``end-at`` will keep
   the line and ``end-before`` skip the first line).

   .. note::

      If you want to select only ``[second-section]`` of ini file like the
      following, you can use ``:start-at: [second-section]`` and
      ``:end-before: [third-section]``:

      .. code-block:: ini

         [first-section]

         var_in_first=true

         [second-section]

         var_in_second=true

         [third-section]

         var_in_third=true

      Useful cases of these option is working with tag comments.
      ``:start-after: [initialize]`` and ``:end-before: [initialized]`` options
      keep lines between comments:

      .. code-block:: py

         if __name__ == "__main__":
             # [initialize]
             app.start(":8000")
             # [initialized]


   When lines have been selected in any of the ways described above, the line
   numbers in ``emphasize-lines`` refer to those selected lines, counted
   consecutively starting at ``1``.

   When specifying particular parts of a file to display, it can be useful to
   display the original line numbers. This can be done using the
   ``lineno-match`` option, which is however allowed only when the selection
   consists of contiguous lines.

   You can prepend and/or append a line to the included code, using the
   ``prepend`` and ``append`` option, respectively.  This is useful e.g. for
   highlighting PHP code that doesn't include the ``<?php``/``?>`` markers.

   If you want to show the diff of the code, you can specify the old file by
   giving a ``diff`` option::

      .. literalinclude:: example.py
         :diff: example.py.orig

   This shows the diff between ``example.py`` and ``example.py.orig`` with
   unified diff format.

   A ``force`` option can ignore minor errors on highlighting.

   .. versionchanged:: 0.4.3
      Added the ``encoding`` option.

   .. versionchanged:: 0.6
      Added the ``pyobject``, ``lines``, ``start-after`` and ``end-before``
      options, as well as support for absolute filenames.

   .. versionchanged:: 1.0
      Added the ``prepend``, ``append``, and ``tab-width`` options.

   .. versionchanged:: 1.3
      Added the ``diff``, ``lineno-match``, ``caption``, ``name``, and
      ``dedent`` options.

   .. versionchanged:: 1.4
      Added the ``class`` option.

   .. versionchanged:: 1.5
      Added the ``start-at``, and ``end-at`` options.

   .. versionchanged:: 1.6
      With both ``start-after`` and ``lines`` in use, the first line as per
      ``start-after`` is considered to be with line number ``1`` for ``lines``.

   .. versionchanged:: 2.1
      Added the ``force`` option.

   .. versionchanged:: 3.5
      Support automatic dedent.

.. _glossary-directive:

Glossary
--------

.. rst:directive:: .. glossary::

   This directive must contain a reST definition-list-like markup with terms and
   definitions.  The definitions will then be referenceable with the
   :rst:role:`term` role.  Example::

      .. glossary::

         environment
            A structure where information about all documents under the root is
            saved, and used for cross-referencing.  The environment is pickled
            after the parsing stage, so that successive runs only need to read
            and parse new and changed documents.

         source directory
            The directory which, including its subdirectories, contains all
            source files for one Sphinx project.

   In contrast to regular definition lists, *multiple* terms per entry are
   allowed, and inline markup is allowed in terms.  You can link to all of the
   terms.  For example::

      .. glossary::

         term 1
         term 2
            Definition of both terms.

   (When the glossary is sorted, the first term determines the sort order.)

   If you want to specify "grouping key" for general index entries, you can put
   a "key" as "term : key". For example::

      .. glossary::

         term 1 : A
         term 2 : B
            Definition of both terms.

   Note that "key" is used for grouping key as is.
   The "key" isn't normalized; key "A" and "a" become different groups.
   The whole characters in "key" is used instead of a first character; it is
   used for "Combining Character Sequence" and "Surrogate Pairs" grouping key.

   In i18n situation, you can specify "localized term : key" even if original
   text only have "term" part. In this case, translated "localized term" will be
   categorized in "key" group.

   .. versionadded:: 0.6
      You can now give the glossary directive a ``:sorted:`` flag that will
      automatically sort the entries alphabetically.

   .. versionchanged:: 1.1
      Now supports multiple terms and inline markup in terms.

   .. versionchanged:: 1.4
      Index key for glossary term should be considered *experimental*.

   .. versionchanged:: 4.4
      In internationalized documentation, the ``:sorted:`` flag sorts
      according to translated terms.

Meta-information markup
-----------------------

.. rst:directive:: .. sectionauthor:: name <email>

   Identifies the author of the current section.  The argument should include
   the author's name such that it can be used for presentation and email
   address.  The domain name portion of the address should be lower case.
   Example::

      .. sectionauthor:: Guido van Rossum <guido@python.org>

   By default, this markup isn't reflected in the output in any way (it helps
   keep track of contributions), but you can set the configuration value
   :confval:`show_authors` to ``True`` to make them produce a paragraph in the
   output.


.. rst:directive:: .. codeauthor:: name <email>

   The :rst:dir:`codeauthor` directive, which can appear multiple times, names
   the authors of the described code, just like :rst:dir:`sectionauthor` names
   the author(s) of a piece of documentation.  It too only produces output if
   the :confval:`show_authors` configuration value is ``True``.


Index-generating markup
-----------------------

Sphinx automatically creates index entries from all object descriptions (like
functions, classes or attributes) like discussed in
:doc:`/usage/domains/index`.

However, there is also explicit markup available, to make the index more
comprehensive and enable index entries in documents where information is not
mainly contained in information units, such as the language reference.

.. rst:directive:: .. index:: <entries>

   This directive contains one or more index entries.  Each entry consists of a
   type and a value, separated by a colon.

   For example::

      .. index::
         single: execution; context
         pair: module; __main__
         pair: module; sys
         triple: module; search; path
         seealso: scope

      The execution context
      ---------------------

      ...

   This directive contains five entries, which will be converted to entries in
   the generated index which link to the exact location of the index statement
   (or, in case of offline media, the corresponding page number).

   Since index directives generate cross-reference targets at their location in
   the source, it makes sense to put them *before* the thing they refer to --
   e.g. a heading, as in the example above.

   The possible entry types are:

   single
      Creates a single index entry.
      Can be made a sub-entry by separating the sub-entry text with a semicolon
      (this notation is also used below to describe what entries are created).
      Examples:

      .. code:: reStructuredText

         .. index:: single: execution
                    single: execution; context

      - ``single: execution`` creates an index entry labelled ``execution``.
      - ``single: execution; context`` creates an sub-entry of ``execution``
        labelled ``context``.
   pair
      A shortcut to create two index entries.
      The pair of values must be separated by a semicolon.
      Example:

      .. code:: reStructuredText

         .. index:: pair: loop; statement

      This would create two index entries; ``loop; statement`` and ``statement; loop``.
   triple
      A shortcut to create three index entries.
      All three values must be separated by a semicolon.
      Example:

      .. code:: reStructuredText

         .. index:: triple: module; search; path

      This would create three index entries; ``module; search path``,
      ``search; path, module``, and ``path; module search``.
   see
      A shortcut to create an index entry that refers to another entry.
      Example:

      .. code:: reStructuredText

         .. index:: see: entry; other

      This would create an index entry referring from ``entry`` to ``other``
      (i.e. 'entry': See 'other').
   seealso
      Like ``see``, but inserts 'see also' instead of 'see'.
   module, keyword, operator, object, exception, statement, builtin
      These **deprecated** shortcuts all create two index entries.
      For example, ``module: hashlib`` creates the entries ``module; hashlib``
      and ``hashlib; module``.

      .. deprecated:: 1.0
         These Python-specific entry types are deprecated.

      .. versionchanged:: 7.1
         Removal version set to Sphinx 9.0.
         Using these entry types will now emit warnings with the ``index`` category.

   You can mark up "main" index entries by prefixing them with an exclamation
   mark.  The references to "main" entries are emphasized in the generated
   index.  For example, if two pages contain ::

      .. index:: Python

   and one page contains ::

      .. index:: ! Python

   then the backlink to the latter page is emphasized among the three backlinks.

   For index directives containing only "single" entries, there is a shorthand
   notation::

      .. index:: BNF, grammar, syntax, notation

   This creates four index entries.

   .. versionchanged:: 1.1
      Added ``see`` and ``seealso`` types, as well as marking main entries.

   .. rubric:: options

   .. rst:directive:option:: name: a label for hyperlink
      :type: text

      Define implicit target name that can be referenced by using
      :rst:role:`ref`.  For example::

        .. index:: Python
           :name: py-index

   .. versionadded:: 3.0

.. rst:role:: index

   While the :rst:dir:`index` directive is a block-level markup and links to the
   beginning of the next paragraph, there is also a corresponding role that sets
   the link target directly where it is used.

   The content of the role can be a simple phrase, which is then kept in the
   text and used as an index entry.  It can also be a combination of text and
   index entry, styled like with explicit targets of cross-references.  In that
   case, the "target" part can be a full entry as described for the directive
   above.  For example::

      This is a normal reST :index:`paragraph` that contains several
      :index:`index entries <pair: index; entry>`.

   .. versionadded:: 1.1


.. _tags:

Including content based on tags
-------------------------------

.. rst:directive:: .. only:: <expression>

   Include the content of the directive only if the *expression* is true.  The
   expression should consist of tags, like this::

      .. only:: html and draft

   Undefined tags are false, defined tags (via the ``-t`` command-line option or
   within :file:`conf.py`, see :ref:`here <conf-tags>`) are true.  Boolean
   expressions, also using parentheses (like ``(latex or html) and draft``) are
   supported.

   The *format* and the *name* of the current builder (``html``, ``latex`` or
   ``text``) are always set as a tag [#]_.  To make the distinction between
   format and name explicit, they are also added with the prefix ``format_`` and
   ``builder_``, e.g. the epub builder defines the tags  ``html``, ``epub``,
   ``format_html`` and ``builder_epub``.

   These standard tags are set *after* the configuration file is read, so they
   are not available there.

   All tags must follow the standard Python identifier syntax as set out in
   the `Identifiers and keywords
   <https://docs.python.org/3/reference/lexical_analysis.html#identifiers>`_
   documentation.  That is, a tag expression may only consist of tags that
   conform to the syntax of Python variables.  In ASCII, this consists of the
   uppercase and lowercase letters ``A`` through ``Z``, the underscore ``_``
   and, except for the first character, the digits ``0`` through ``9``.

   .. versionadded:: 0.6
   .. versionchanged:: 1.2
      Added the name of the builder and the prefixes.

   .. warning::

      This directive is designed to control only content of document.  It could
      not control sections, labels and so on.

.. _table-directives:

Tables
------

Use :ref:`reStructuredText tables <rst-tables>`, i.e. either

- grid table syntax (:duref:`ref <grid-tables>`),
- simple table syntax (:duref:`ref <simple-tables>`),
- :dudir:`csv-table` syntax,
- or :dudir:`list-table` syntax.

The :dudir:`table` directive serves as optional wrapper of the *grid* and
*simple* syntaxes.

They work fine in HTML output, but rendering tables to LaTeX is complex.
Check the :confval:`latex_table_style`.

.. versionchanged:: 1.6
   Merged cells (multi-row, multi-column, both) from grid tables containing
   complex contents such as multiple paragraphs, blockquotes, lists, literal
   blocks, will render correctly to LaTeX output.

.. rst:directive:: .. tabularcolumns:: column spec

   This directive influences only the LaTeX output for the next table in
   source.  The mandatory argument is a column specification (known as an
   "alignment preamble" in LaTeX idiom).  Please refer to a LaTeX
   documentation, such as the `wiki page`_, for basics of such a column
   specification.

   .. _wiki page: https://en.wikibooks.org/wiki/LaTeX/Tables

   .. versionadded:: 0.3

   .. note::

      :rst:dir:`tabularcolumns` conflicts with ``:widths:`` option of table
      directives.  If both are specified, ``:widths:`` option will be ignored.

   Sphinx will render tables with more than 30 rows with ``longtable``.
   Besides the ``l``, ``r``, ``c`` and ``p{width}`` column specifiers, one can
   also use ``\X{a}{b}`` (new in version 1.5) which configures the column
   width to be a fraction ``a/b`` of the total line width and ``\Y{f}`` (new
   in version 1.6) where ``f`` is a decimal: for example ``\Y{0.2}`` means that
   the column will occupy ``0.2`` times the line width.

   When this directive is used for a table with at most 30 rows, Sphinx will
   render it with ``tabulary``.  One can then use specific column types ``L``
   (left), ``R`` (right), ``C`` (centered) and ``J`` (justified).  They have
   the effect of a ``p{width}`` (i.e. each cell is a LaTeX ``\parbox``) with
   the specified internal text alignment and an automatically computed
   ``width``.

   .. warning::

      - Cells that contain list-like elements such as object descriptions,
        blockquotes or any kind of lists are not compatible with the ``LRCJ``
        column types.  The column type must then be some ``p{width}`` with an
        explicit ``width`` (or ``\X{a}{b}`` or ``\Y{f}``).

      - Literal blocks do not work with ``tabulary`` at all.  Sphinx will
        fall back to ``tabular`` or ``longtable`` environments and generate a
        suitable column specification.

In absence of the :rst:dir:`tabularcolumns` directive, and for a table with at
most 30 rows and no problematic cells as described in the above warning,
Sphinx uses ``tabulary`` and the ``J`` column-type for every column.

.. versionchanged:: 1.6

   Formerly, the ``L`` column-type was used (text is flushed-left).  To revert
   to this, include ``\newcolumntype{T}{L}`` in the LaTeX preamble, as in fact
   Sphinx uses ``T`` and sets it by default to be an alias of ``J``.

.. hint::

   A frequent issue with ``tabulary`` is that columns with little contents
   appear to be "squeezed".  One can add to the LaTeX preamble for example
   ``\setlength{\tymin}{40pt}`` to ensure a minimal column width of ``40pt``,
   the ``tabulary`` default of ``10pt`` being too small.

.. hint::

   To force usage of the LaTeX ``longtable`` environment pass ``longtable`` as
   a ``:class:`` option to :dudir:`table`, :dudir:`csv-table`, or
   :dudir:`list-table`.  Use :ref:`rst-class <rstclass>` for other tables.

Math
----

The input language for mathematics is LaTeX markup.  This is the de-facto
standard for plain-text math notation and has the added advantage that no
further translation is necessary when building LaTeX output.

Keep in mind that when you put math markup in **Python docstrings** read by
:mod:`autodoc <sphinx.ext.autodoc>`, you either have to double all backslashes,
or use Python raw strings (``r"raw"``).

.. rst:directive:: math

   Directive for displayed math (math that takes the whole line for itself).

   The directive supports multiple equations, which should be separated by a
   blank line::

      .. math::

         (a + b)^2 = a^2 + 2ab + b^2

         (a - b)^2 = a^2 - 2ab + b^2

   In addition, each single equation is set within a ``split`` environment,
   which means that you can have multiple aligned lines in an equation,
   aligned at ``&`` and separated by ``\\``::

      .. math::

         (a + b)^2  &=  (a + b)(a + b) \\
                    &=  a^2 + 2ab + b^2

   For more details, look into the documentation of the `AmSMath LaTeX
   package`_.

   When the math is only one line of text, it can also be given as a directive
   argument::

      .. math:: (a + b)^2 = a^2 + 2ab + b^2

   Normally, equations are not numbered.  If you want your equation to get a
   number, use the ``label`` option.  When given, it selects an internal label
   for the equation, by which it can be cross-referenced, and causes an equation
   number to be issued.  See :rst:role:`eq` for an example.  The numbering
   style depends on the output format.

   There is also an option ``nowrap`` that prevents any wrapping of the given
   math in a math environment.  When you give this option, you must make sure
   yourself that the math is properly set up.  For example::

      .. math::
         :nowrap:

         \begin{eqnarray}
            y    & = & ax^2 + bx + c \\
            f(x) & = & x^2 + 2xy + y^2
         \end{eqnarray}

.. _AmSMath LaTeX package: https://www.ams.org/publications/authors/tex/amslatex

.. seealso::

   :ref:`math-support`
      Rendering options for math with HTML builders.

   :confval:`latex_engine`
      Explains how to configure LaTeX builder to support Unicode literals in
      math mark-up.


Grammar production displays
---------------------------

Special markup is available for displaying the productions of a formal grammar.
The markup is simple and does not attempt to model all aspects of BNF (or any
derived forms), but provides enough to allow context-free grammars to be
displayed in a way that causes uses of a symbol to be rendered as hyperlinks to
the definition of the symbol.  There is this directive:

.. rst:directive:: .. productionlist:: [productionGroup]

   This directive is used to enclose a group of productions.  Each production
   is given on a single line and consists of a name, separated by a colon from
   the following definition.  If the definition spans multiple lines, each
   continuation line must begin with a colon placed at the same column as in
   the first line.
   Blank lines are not allowed within ``productionlist`` directive arguments.

   The definition can contain token names which are marked as interpreted text
   (e.g., "``sum ::= `integer` "+" `integer```") -- this generates
   cross-references to the productions of these tokens.  Outside of the
   production list, you can reference to token productions using
   :rst:role:`token`.

   The *productionGroup* argument to :rst:dir:`productionlist` serves to
   distinguish different sets of production lists that belong to different
   grammars.  Multiple production lists with the same *productionGroup* thus
   define rules in the same scope.

   Inside of the production list, tokens implicitly refer to productions
   from the current group. You can refer to the production of another
   grammar by prefixing the token with its group name and a colon, e.g,
   "``otherGroup:sum``". If the group of the token should not be shown in
   the production, it can be prefixed by a tilde, e.g.,
   "``~otherGroup:sum``". To refer to a production from an unnamed
   grammar, the token should be prefixed by a colon, e.g., "``:sum``".

   Outside of the production list,
   if you have given a *productionGroup* argument you must prefix the
   token name in the cross-reference with the group name and a colon,
   e.g., "``myGroup:sum``" instead of just "``sum``".
   If the group should not be shown in the title of the link either
   an explicit title can be given (e.g., "``myTitle <myGroup:sum>``"),
   or the target can be prefixed with a tilde (e.g., "``~myGroup:sum``").

   Note that no further reST parsing is done in the production, so that you
   don't have to escape ``*`` or ``|`` characters.

The following is an example taken from the Python Reference Manual::

   .. productionlist::
      try_stmt: try1_stmt | try2_stmt
      try1_stmt: "try" ":" `suite`
               : ("except" [`expression` ["," `target`]] ":" `suite`)+
               : ["else" ":" `suite`]
               : ["finally" ":" `suite`]
      try2_stmt: "try" ":" `suite`
               : "finally" ":" `suite`


.. rubric:: Footnotes

.. [#] The LaTeX writer only refers the ``maxdepth`` option of first toctree
       directive in the document.

.. [#] A note on available globbing syntax: you can use the standard shell
       constructs ``*``, ``?``, ``[...]`` and ``[!...]`` with the feature that
       these all don't match slashes.  A double star ``**`` can be used to
       match any sequence of characters *including* slashes.

.. [#] There is a standard ``.. include`` directive, but it raises errors if the
       file is not found.  This one only emits a warning.

.. [#] For most builders name and format are the same. At the moment only
       builders derived from the html builder distinguish between the builder
       format and the builder name.

       Note that the current builder tag is not available in ``conf.py``, it is
       only available after the builder is initialized.