/
configuration.rst
3049 lines (2049 loc) · 99.7 KB
/
configuration.rst
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
.. highlight:: python
.. _build-config:
=============
Configuration
=============
.. module:: conf
:synopsis: Build configuration file.
The :term:`configuration directory` must contain a file named :file:`conf.py`.
This file (containing Python code) is called the "build configuration file"
and contains (almost) all configuration needed to customize Sphinx input
and output behavior.
An optional file `docutils.conf`_ can be added to the configuration
directory to adjust `Docutils`_ configuration if not otherwise overridden or
set by Sphinx.
.. _`docutils`: https://docutils.sourceforge.io/
.. _`docutils.conf`: https://docutils.sourceforge.io/docs/user/config.html
The configuration file is executed as Python code at build time (using
:func:`importlib.import_module`, and with the current directory set to its
containing directory), and therefore can execute arbitrarily complex code.
Sphinx then reads simple names from the file's namespace as its configuration.
Important points to note:
* If not otherwise documented, values must be strings, and their default is the
empty string.
* The term "fully-qualified name" refers to a string that names an importable
Python object inside a module; for example, the FQN
``"sphinx.builders.Builder"`` means the ``Builder`` class in the
``sphinx.builders`` module.
* Remember that document names use ``/`` as the path separator and don't
contain the file name extension.
* Since :file:`conf.py` is read as a Python file, the usual rules apply for
encodings and Unicode support.
* The contents of the config namespace are pickled (so that Sphinx can find out
when configuration changes), so it may not contain unpickleable values --
delete them from the namespace with ``del`` if appropriate. Modules are
removed automatically, so you don't need to ``del`` your imports after use.
.. _conf-tags:
* There is a special object named ``tags`` available in the config file.
It can be used to query and change the tags (see :ref:`tags`). Use
``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')``
to change. Only tags set via the ``-t`` command-line option or via
``tags.add('tag')`` can be queried using ``tags.has('tag')``.
Note that the current builder tag is not available in ``conf.py``, as it is
created *after* the builder is initialized.
Project information
-------------------
.. confval:: project
The documented project's name.
.. confval:: author
The author name(s) of the document. The default value is ``'unknown'``.
.. confval:: copyright
A copyright statement in the style ``'2008, Author Name'``.
.. versionchanged:: 7.1
The value may now be a sequence of copyright statements in the above form,
which will be displayed each to their own line.
.. confval:: project_copyright
An alias of :confval:`copyright`.
.. versionadded:: 3.5
.. confval:: version
The major project version, used as the replacement for ``|version|``. For
example, for the Python documentation, this may be something like ``2.6``.
.. confval:: release
The full project version, used as the replacement for ``|release|`` and
e.g. in the HTML templates. For example, for the Python documentation, this
may be something like ``2.6.0rc1``.
If you don't need the separation provided between :confval:`version` and
:confval:`release`, just set them both to the same value.
General configuration
---------------------
.. confval:: extensions
A list of strings that are module names of :doc:`extensions
<extensions/index>`. These can be extensions coming with Sphinx (named
``sphinx.ext.*``) or custom ones.
Note that you can extend :data:`sys.path` within the conf file if your
extensions live in another directory -- but make sure you use absolute paths.
If your extension path is relative to the :term:`configuration directory`,
use :func:`os.path.abspath` like so::
import sys, os
sys.path.append(os.path.abspath('sphinxext'))
extensions = ['extname']
That way, you can load an extension called ``extname`` from the subdirectory
``sphinxext``.
The configuration file itself can be an extension; for that, you only need
to provide a :func:`setup` function in it.
.. confval:: source_suffix
The file extensions of source files. Sphinx considers the files with this
suffix as sources. The value can be a dictionary mapping file extensions
to file types. For example::
source_suffix = {
'.rst': 'restructuredtext',
'.txt': 'restructuredtext',
'.md': 'markdown',
}
By default, Sphinx only supports ``'restructuredtext'`` file type. You can
add a new file type using source parser extensions. Please read a document
of the extension to know which file type the extension supports.
The value may also be a list of file extensions: then Sphinx will consider
that they all map to the ``'restructuredtext'`` file type.
Default is ``{'.rst': 'restructuredtext'}``.
.. note:: file extensions have to start with a dot (e.g. ``.rst``).
.. versionchanged:: 1.3
Can now be a list of extensions.
.. versionchanged:: 1.8
Support file type mapping
.. confval:: source_encoding
The encoding of all reST source files. The recommended encoding, and the
default value, is ``'utf-8-sig'``.
.. versionadded:: 0.5
Previously, Sphinx accepted only UTF-8 encoded sources.
.. confval:: source_parsers
If given, a dictionary of parser classes for different source suffices. The
keys are the suffix, the values can be either a class or a string giving a
fully-qualified name of a parser class. The parser class can be either
``docutils.parsers.Parser`` or :class:`sphinx.parsers.Parser`. Files with a
suffix that is not in the dictionary will be parsed with the default
reStructuredText parser.
For example::
source_parsers = {'.md': 'recommonmark.parser.CommonMarkParser'}
.. note::
Refer to :doc:`/usage/markdown` for more information on using Markdown
with Sphinx.
.. versionadded:: 1.3
.. deprecated:: 1.8
Now Sphinx provides an API :meth:`.Sphinx.add_source_parser` to register
a source parser. Please use it instead.
.. confval:: master_doc
Same as :confval:`root_doc`.
.. versionchanged:: 4.0
Renamed ``master_doc`` to ``root_doc``.
.. confval:: root_doc
The document name of the "root" document, that is, the document that
contains the root :rst:dir:`toctree` directive. Default is ``'index'``.
.. versionchanged:: 2.0
The default is changed to ``'index'`` from ``'contents'``.
.. versionchanged:: 4.0
Renamed ``root_doc`` from ``master_doc``.
.. confval:: exclude_patterns
A list of glob-style patterns [1]_ that should be excluded when looking for
source files. They are matched against the source file names relative
to the source directory, using slashes as directory separators on all
platforms.
Example patterns:
- ``'library/xml.rst'`` -- ignores the ``library/xml.rst`` file
- ``'library/xml'`` -- ignores the ``library/xml`` directory
- ``'library/xml*'`` -- ignores all files and directories starting with
``library/xml``
- ``'**/.svn'`` -- ignores all ``.svn`` directories
:confval:`exclude_patterns` is also consulted when looking for static files
in :confval:`html_static_path` and :confval:`html_extra_path`.
.. versionadded:: 1.0
.. confval:: include_patterns
A list of glob-style patterns [1]_ that are used to find source files. They
are matched against the source file names relative to the source directory,
using slashes as directory separators on all platforms. The default is ``**``,
meaning that all files are recursively included from the source directory.
Example patterns:
- ``'**'`` -- all files in the source directory and subdirectories, recursively
- ``'library/xml'`` -- just the ``library/xml`` directory
- ``'library/xml*'`` -- all files and directories starting with ``library/xml``
- ``'**/doc'`` -- all ``doc`` directories (this might be useful if
documentation is co-located with source files)
.. versionadded:: 5.1
.. confval:: templates_path
A list of paths that contain extra templates (or templates that overwrite
builtin/theme-specific templates). Relative paths are taken as relative to
the configuration directory.
.. versionchanged:: 1.3
As these files are not meant to be built, they are automatically added to
:confval:`exclude_patterns`.
.. confval:: template_bridge
A string with the fully-qualified name of a callable (or simply a class)
that returns an instance of :class:`~sphinx.application.TemplateBridge`.
This instance is then used to render HTML documents, and possibly the output
of other builders (currently the changes builder). (Note that the template
bridge must be made theme-aware if HTML themes are to be used.)
.. confval:: rst_epilog
.. index:: pair: global; substitutions
A string of reStructuredText that will be included at the end of every source
file that is read. This is a possible place to add substitutions that should
be available in every file (another being :confval:`rst_prolog`). An
example::
rst_epilog = """
.. |psf| replace:: Python Software Foundation
"""
.. versionadded:: 0.6
.. confval:: rst_prolog
.. index:: pair: global; substitutions
A string of reStructuredText that will be included at the beginning of every
source file that is read. This is a possible place to add substitutions that
should be available in every file (another being :confval:`rst_epilog`). An
example::
rst_prolog = """
.. |psf| replace:: Python Software Foundation
"""
.. versionadded:: 1.0
.. confval:: primary_domain
.. index:: default; domain
primary; domain
The name of the default :doc:`domain </usage/restructuredtext/domains>`.
Can also be ``None`` to disable a default domain. The default is ``'py'``.
Those objects in other domains (whether the domain name is given explicitly,
or selected by a :rst:dir:`default-domain` directive) will have the domain
name explicitly prepended when named (e.g., when the default domain is C,
Python functions will be named "Python function", not just "function").
.. versionadded:: 1.0
.. confval:: default_role
.. index:: default; role
The name of a reST role (builtin or Sphinx extension) to use as the default
role, that is, for text marked up ```like this```. This can be set to
``'py:obj'`` to make ```filter``` a cross-reference to the Python function
"filter". The default is ``None``, which doesn't reassign the default role.
The default role can always be set within individual documents using the
standard reST :dudir:`default-role` directive.
.. versionadded:: 0.4
.. confval:: keep_warnings
If true, keep warnings as "system message" paragraphs in the built
documents. Regardless of this setting, warnings are always written to the
standard error stream when ``sphinx-build`` is run.
The default is ``False``, the pre-0.5 behavior was to always keep them.
.. versionadded:: 0.5
.. confval:: suppress_warnings
A list of warning types to suppress arbitrary warning messages.
Sphinx supports following warning types:
* ``app.add_node``
* ``app.add_directive``
* ``app.add_role``
* ``app.add_generic_role``
* ``app.add_source_parser``
* ``autosectionlabel.*``
* ``download.not_readable``
* ``epub.unknown_project_files``
* ``epub.duplicated_toc_entry``
* ``i18n.inconsistent_references``
* ``index``
* ``image.not_readable``
* ``ref.term``
* ``ref.ref``
* ``ref.numref``
* ``ref.keyword``
* ``ref.option``
* ``ref.citation``
* ``ref.footnote``
* ``ref.doc``
* ``ref.python``
* ``misc.highlighting_failure``
* ``toc.circular``
* ``toc.excluded``
* ``toc.not_readable``
* ``toc.secnum``
You can choose from these types. You can also give only the first
component to exclude all warnings attached to it.
Now, this option should be considered *experimental*.
.. versionadded:: 1.4
.. versionchanged:: 1.5
Added ``misc.highlighting_failure``
.. versionchanged:: 1.5.1
Added ``epub.unknown_project_files``
.. versionchanged:: 1.6
Added ``ref.footnote``
.. versionchanged:: 2.1
Added ``autosectionlabel.*``
.. versionchanged:: 3.3.0
Added ``epub.duplicated_toc_entry``
.. versionchanged:: 4.3
Added ``toc.excluded`` and ``toc.not_readable``
.. versionadded:: 4.5
Added ``i18n.inconsistent_references``
.. versionadded:: 7.1
Added ``index`` warning type.
.. confval:: needs_sphinx
If set to a ``major.minor`` version string like ``'1.1'``, Sphinx will
compare it with its version and refuse to build if it is too old. Default
is no requirement.
.. versionadded:: 1.0
.. versionchanged:: 1.4
also accepts micro version string
.. confval:: needs_extensions
This value can be a dictionary specifying version requirements for
extensions in :confval:`extensions`, e.g. ``needs_extensions =
{'sphinxcontrib.something': '1.5'}``. The version strings should be in the
form ``major.minor``. Requirements do not have to be specified for all
extensions, only for those you want to check.
This requires that the extension specifies its version to Sphinx (see
:ref:`dev-extensions` for how to do that).
.. versionadded:: 1.3
.. confval:: manpages_url
A URL to cross-reference :rst:role:`manpage` roles. If this is
defined to ``https://manpages.debian.org/{path}``, the
:literal:`:manpage:`man(1)`` role will link to
<https://manpages.debian.org/man(1)>. The patterns available are:
* ``page`` - the manual page (``man``)
* ``section`` - the manual section (``1``)
* ``path`` - the original manual page and section specified (``man(1)``)
This also supports manpages specified as ``man.1``.
.. note:: This currently affects only HTML writers but could be
expanded in the future.
.. versionadded:: 1.7
.. confval:: nitpicky
If true, Sphinx will warn about *all* references where the target cannot be
found. Default is ``False``. You can activate this mode temporarily using
the :option:`-n <sphinx-build -n>` command-line switch.
.. versionadded:: 1.0
.. confval:: nitpick_ignore
A set or list of ``(type, target)`` tuples (by default empty) that should be
ignored when generating warnings in "nitpicky mode". Note that ``type``
should include the domain name if present. Example entries would be
``('py:func', 'int')`` or ``('envvar', 'LD_LIBRARY_PATH')``.
.. versionadded:: 1.1
.. versionchanged:: 6.2
Changed allowable container types to a set, list, or tuple
.. confval:: nitpick_ignore_regex
An extended version of :confval:`nitpick_ignore`, which instead interprets
the ``type`` and ``target`` strings as regular expressions. Note, that the
regular expression must match the whole string (as if the ``^`` and ``$``
markers were inserted).
For example, ``(r'py:.*', r'foo.*bar\.B.*')`` will ignore nitpicky warnings
for all python entities that start with ``'foo'`` and have ``'bar.B'`` in
them, such as ``('py:const', 'foo_package.bar.BAZ_VALUE')`` or
``('py:class', 'food.bar.Barman')``.
.. versionadded:: 4.1
.. versionchanged:: 6.2
Changed allowable container types to a set, list, or tuple
.. confval:: numfig
If true, figures, tables and code-blocks are automatically numbered if they
have a caption. The :rst:role:`numref` role is enabled.
Obeyed so far only by HTML and LaTeX builders. Default is ``False``.
.. note::
The LaTeX builder always assigns numbers whether this option is enabled
or not.
.. versionadded:: 1.3
.. confval:: numfig_format
A dictionary mapping ``'figure'``, ``'table'``, ``'code-block'`` and
``'section'`` to strings that are used for format of figure numbers.
As a special character, ``%s`` will be replaced to figure number.
Default is to use ``'Fig. %s'`` for ``'figure'``, ``'Table %s'`` for
``'table'``, ``'Listing %s'`` for ``'code-block'`` and ``'Section %s'`` for
``'section'``.
.. versionadded:: 1.3
.. confval:: numfig_secnum_depth
- if set to ``0``, figures, tables and code-blocks are continuously numbered
starting at ``1``.
- if ``1`` (default) numbers will be ``x.1``, ``x.2``, ... with ``x``
the section number (top level sectioning; no ``x.`` if no section).
This naturally applies only if section numbering has been activated via
the ``:numbered:`` option of the :rst:dir:`toctree` directive.
- ``2`` means that numbers will be ``x.y.1``, ``x.y.2``, ... if located in
a sub-section (but still ``x.1``, ``x.2``, ... if located directly under a
section and ``1``, ``2``, ... if not in any top level section.)
- etc...
.. versionadded:: 1.3
.. versionchanged:: 1.7
The LaTeX builder obeys this setting (if :confval:`numfig` is set to
``True``).
.. confval:: smartquotes
If true, the `Docutils Smart Quotes transform`__, originally based on
`SmartyPants`__ (limited to English) and currently applying to many
languages, will be used to convert quotes and dashes to typographically
correct entities. Default: ``True``.
__ https://docutils.sourceforge.io/docs/user/smartquotes.html
__ https://daringfireball.net/projects/smartypants/
.. versionadded:: 1.6.6
It replaces deprecated :confval:`html_use_smartypants`.
It applies by default to all builders except ``man`` and ``text``
(see :confval:`smartquotes_excludes`.)
A `docutils.conf`__ file located in the configuration directory (or a
global :file:`~/.docutils` file) is obeyed unconditionally if it
*deactivates* smart quotes via the corresponding `Docutils option`__. But
if it *activates* them, then :confval:`smartquotes` does prevail.
__ https://docutils.sourceforge.io/docs/user/config.html
__ https://docutils.sourceforge.io/docs/user/config.html#smart-quotes
.. confval:: smartquotes_action
This string customizes the Smart Quotes transform. See the file
:file:`smartquotes.py` at the `Docutils repository`__ for details. The
default ``'qDe'`` educates normal **q**\ uote characters ``"``, ``'``,
em- and en-**D**\ ashes ``---``, ``--``, and **e**\ llipses ``...``.
.. versionadded:: 1.6.6
__ https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
.. confval:: smartquotes_excludes
This is a ``dict`` whose default is::
{'languages': ['ja'], 'builders': ['man', 'text']}
Each entry gives a sufficient condition to ignore the
:confval:`smartquotes` setting and deactivate the Smart Quotes transform.
Accepted keys are as above ``'builders'`` or ``'languages'``.
The values are lists.
.. note:: Currently, in case of invocation of :program:`make` with multiple
targets, the first target name is the only one which is tested against
the ``'builders'`` entry and it decides for all. Also, a ``make text``
following ``make html`` needs to be issued in the form ``make text
O="-E"`` to force re-parsing of source files, as the cached ones are
already transformed. On the other hand the issue does not arise with
direct usage of :program:`sphinx-build` as it caches
(in its default usage) the parsed source files in per builder locations.
.. hint:: An alternative way to effectively deactivate (or customize) the
smart quotes for a given builder, for example ``latex``, is to use
``make`` this way:
.. code-block:: console
make latex O="-D smartquotes_action="
This can follow some ``make html`` with no problem, in contrast to the
situation from the prior note.
.. versionadded:: 1.6.6
.. confval:: user_agent
A User-Agent of Sphinx. It is used for a header on HTTP access (ex.
linkcheck, intersphinx and so on). Default is ``"Sphinx/X.Y.Z
requests/X.Y.Z python/X.Y.Z"``.
.. versionadded:: 2.3
.. confval:: tls_verify
If true, Sphinx verifies server certifications. Default is ``True``.
.. versionadded:: 1.5
.. confval:: tls_cacerts
A path to a certification file of CA or a path to directory which
contains the certificates. This also allows a dictionary mapping
hostname to the path to certificate file.
The certificates are used to verify server certifications.
.. versionadded:: 1.5
.. tip:: Sphinx uses requests_ as a HTTP library internally.
Therefore, Sphinx refers a certification file on the
directory pointed ``REQUESTS_CA_BUNDLE`` environment
variable if ``tls_cacerts`` not set.
.. _requests: https://requests.readthedocs.io/en/master/
.. confval:: today
today_fmt
These values determine how to format the current date, used as the
replacement for ``|today|``.
* If you set :confval:`today` to a non-empty value, it is used.
* Otherwise, the current time is formatted using :func:`time.strftime` and
the format given in :confval:`today_fmt`.
The default is now :confval:`today` and a :confval:`today_fmt` of ``'%b %d,
%Y'`` (or, if translation is enabled with :confval:`language`, an equivalent
format for the selected locale).
.. confval:: highlight_language
The default language to highlight source code in. The default is
``'default'``. It is similar to ``'python3'``; it is mostly a superset of
``'python'`` but it fallbacks to ``'none'`` without warning if failed.
``'python3'`` and other languages will emit warning if failed.
The value should be a valid Pygments lexer name, see
:ref:`code-examples` for more details.
.. versionadded:: 0.5
.. versionchanged:: 1.4
The default is now ``'default'``. If you prefer Python 2 only
highlighting, you can set it back to ``'python'``.
.. confval:: highlight_options
A dictionary that maps language names to options for the lexer modules of
Pygments. These are lexer-specific; for the options understood by each,
see the `Pygments documentation <https://pygments.org/docs/lexers>`_.
Example::
highlight_options = {
'default': {'stripall': True},
'php': {'startinline': True},
}
A single dictionary of options are also allowed. Then it is recognized
as options to the lexer specified by :confval:`highlight_language`::
# configuration for the ``highlight_language``
highlight_options = {'stripall': True}
.. versionadded:: 1.3
.. versionchanged:: 3.5
Allow to configure highlight options for multiple languages
.. confval:: pygments_style
The style name to use for Pygments highlighting of source code. If not set,
either the theme's default style or ``'sphinx'`` is selected for HTML
output.
.. versionchanged:: 0.3
If the value is a fully-qualified name of a custom Pygments style class,
this is then used as custom style.
.. confval:: maximum_signature_line_length
If a signature's length in characters exceeds the number set, each
parameter within the signature will be displayed on an individual logical
line.
When ``None`` (the default), there is no maximum length and the entire
signature will be displayed on a single logical line.
A 'logical line' is similar to a hard line break---builders or themes may
choose to 'soft wrap' a single logical line, and this setting does not affect
that behaviour.
Domains may provide options to suppress any hard wrapping on an individual
object directive, such as seen in the C, C++, and Python domains (e.g.
:rst:dir:`py:function:single-line-parameter-list`).
.. versionadded:: 7.1
.. confval:: add_function_parentheses
A boolean that decides whether parentheses are appended to function and
method role text (e.g. the content of ``:func:`input```) to signify that the
name is callable. Default is ``True``.
.. confval:: add_module_names
A boolean that decides whether module names are prepended to all
:term:`object` names (for object types where a "module" of some kind is
defined), e.g. for :rst:dir:`py:function` directives. Default is ``True``.
.. confval:: toc_object_entries
Create table of contents entries for domain objects (e.g. functions, classes,
attributes, etc.). Default is ``True``.
.. confval:: toc_object_entries_show_parents
A string that determines how domain objects (e.g. functions, classes,
attributes, etc.) are displayed in their table of contents entry.
Use ``domain`` to allow the domain to determine the appropriate number of
parents to show. For example, the Python domain would show ``Class.method()``
and ``function()``, leaving out the ``module.`` level of parents.
This is the default setting.
Use ``hide`` to only show the name of the element without any parents
(i.e. ``method()``).
Use ``all`` to show the fully-qualified name for the object
(i.e. ``module.Class.method()``), displaying all parents.
.. versionadded:: 5.2
.. confval:: show_authors
A boolean that decides whether :rst:dir:`codeauthor` and
:rst:dir:`sectionauthor` directives produce any output in the built files.
.. confval:: modindex_common_prefix
A list of prefixes that are ignored for sorting the Python module index
(e.g., if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``,
not ``F``). This can be handy if you document a project that consists of a
single package. Works only for the HTML builder currently. Default is
``[]``.
.. versionadded:: 0.6
.. confval:: trim_footnote_reference_space
Trim spaces before footnote references that are necessary for the reST
parser to recognize the footnote, but do not look too nice in the output.
.. versionadded:: 0.6
.. confval:: trim_doctest_flags
If true, doctest flags (comments looking like ``# doctest: FLAG, ...``) at
the ends of lines and ``<BLANKLINE>`` markers are removed for all code
blocks showing interactive Python sessions (i.e. doctests). Default is
``True``. See the extension :mod:`~sphinx.ext.doctest` for more
possibilities of including doctests.
.. versionadded:: 1.0
.. versionchanged:: 1.1
Now also removes ``<BLANKLINE>``.
.. confval:: strip_signature_backslash
Default is ``False``.
When backslash stripping is enabled then every occurrence of ``\\`` in a
domain directive will be changed to ``\``, even within string literals.
This was the behaviour before version 3.0, and setting this variable to
``True`` will reinstate that behaviour.
.. versionadded:: 3.0
.. confval:: option_emphasise_placeholders
Default is ``False``.
When enabled, emphasise placeholders in :rst:dir:`option` directives.
To display literal braces, escape with a backslash (``\{``). For example,
``option_emphasise_placeholders=True`` and ``.. option:: -foption={TYPE}`` would
render with ``TYPE`` emphasised.
.. versionadded:: 5.1
.. _intl-options:
Options for internationalization
--------------------------------
These options influence Sphinx's *Native Language Support*. See the
documentation on :ref:`intl` for details.
.. confval:: language
The code for the language the docs are written in. Any text automatically
generated by Sphinx will be in that language. Also, Sphinx will try to
substitute individual paragraphs from your documents with the translation
sets obtained from :confval:`locale_dirs`. Sphinx will search
language-specific figures named by :confval:`figure_language_filename`
(e.g. the German version of ``myfigure.png`` will be ``myfigure.de.png``
by default setting) and substitute them for original figures. In the LaTeX
builder, a suitable language will be selected as an option for the *Babel*
package. Default is ``'en'``.
.. versionadded:: 0.5
.. versionchanged:: 1.4
Support figure substitution
.. versionchanged:: 5.0
Currently supported languages by Sphinx are:
* ``ar`` -- Arabic
* ``bg`` -- Bulgarian
* ``bn`` -- Bengali
* ``ca`` -- Catalan
* ``cak`` -- Kaqchikel
* ``cs`` -- Czech
* ``cy`` -- Welsh
* ``da`` -- Danish
* ``de`` -- German
* ``el`` -- Greek
* ``en`` -- English (default)
* ``eo`` -- Esperanto
* ``es`` -- Spanish
* ``et`` -- Estonian
* ``eu`` -- Basque
* ``fa`` -- Iranian
* ``fi`` -- Finnish
* ``fr`` -- French
* ``he`` -- Hebrew
* ``hi`` -- Hindi
* ``hi_IN`` -- Hindi (India)
* ``hr`` -- Croatian
* ``hu`` -- Hungarian
* ``id`` -- Indonesian
* ``it`` -- Italian
* ``ja`` -- Japanese
* ``ko`` -- Korean
* ``lt`` -- Lithuanian
* ``lv`` -- Latvian
* ``mk`` -- Macedonian
* ``nb_NO`` -- Norwegian Bokmal
* ``ne`` -- Nepali
* ``nl`` -- Dutch
* ``pl`` -- Polish
* ``pt`` -- Portuguese
* ``pt_BR`` -- Brazilian Portuguese
* ``pt_PT`` -- European Portuguese
* ``ro`` -- Romanian
* ``ru`` -- Russian
* ``si`` -- Sinhala
* ``sk`` -- Slovak
* ``sl`` -- Slovenian
* ``sq`` -- Albanian
* ``sr`` -- Serbian
* ``sr@latin`` -- Serbian (Latin)
* ``sr_RS`` -- Serbian (Cyrillic)
* ``sv`` -- Swedish
* ``ta`` -- Tamil
* ``te`` -- Telugu
* ``tr`` -- Turkish
* ``uk_UA`` -- Ukrainian
* ``ur`` -- Urdu
* ``vi`` -- Vietnamese
* ``zh_CN`` -- Simplified Chinese
* ``zh_TW`` -- Traditional Chinese
.. confval:: locale_dirs
.. versionadded:: 0.5
Directories in which to search for additional message catalogs (see
:confval:`language`), relative to the source directory. The directories on
this path are searched by the standard :mod:`gettext` module.
Internal messages are fetched from a text domain of ``sphinx``; so if you
add the directory :file:`./locale` to this setting, the message catalogs
(compiled from ``.po`` format using :program:`msgfmt`) must be in
:file:`./locale/{language}/LC_MESSAGES/sphinx.mo`. The text domain of
individual documents depends on :confval:`gettext_compact`.
The default is ``['locales']``.
.. note:: The :option:`-v option for sphinx-build command <sphinx-build -v>`
is useful to check the locale_dirs config works as expected. It
emits debug messages if message catalog directory not found.
.. versionchanged:: 1.5
Use ``locales`` directory as a default value
.. confval:: gettext_allow_fuzzy_translations
If true, "fuzzy" messages in the message catalogs are used for translation.
The default is ``False``.
.. versionadded:: 4.3
.. confval:: gettext_compact
.. versionadded:: 1.1
If true, a document's text domain is its docname if it is a top-level
project file and its very base directory otherwise.
If set to string, all document's text domain is this string, making all
documents use single text domain.
By default, the document ``markup/code.rst`` ends up in the ``markup`` text
domain. With this option set to ``False``, it is ``markup/code``.
.. versionchanged:: 3.3
The string value is now accepted.
.. confval:: gettext_uuid
If true, Sphinx generates uuid information for version tracking in message
catalogs. It is used for:
* Add uid line for each msgids in .pot files.
* Calculate similarity between new msgids and previously saved old msgids.
This calculation takes a long time.
If you want to accelerate the calculation, you can use
``python-levenshtein`` 3rd-party package written in C by using
:command:`pip install python-levenshtein`.
The default is ``False``.
.. versionadded:: 1.3
.. confval:: gettext_location
If true, Sphinx generates location information for messages in message
catalogs.
The default is ``True``.
.. versionadded:: 1.3
.. confval:: gettext_auto_build
If true, Sphinx builds mo file for each translation catalog files.
The default is ``True``.
.. versionadded:: 1.3
.. confval:: gettext_additional_targets
To specify names to enable gettext extracting and translation applying for
i18n additionally. You can specify below names:
:index: index terms
:literal-block: literal blocks (``::`` annotation and ``code-block`` directive)
:doctest-block: doctest block
:raw: raw content
:image: image/figure uri
For example: ``gettext_additional_targets = ['literal-block', 'image']``.
The default is ``[]``.
.. versionadded:: 1.3
.. versionchanged:: 4.0
The alt text for image is translated by default.
.. confval:: figure_language_filename
The filename format for language-specific figures. The default value is
``{root}.{language}{ext}``. It will be expanded to
``dirname/filename.en.png`` from ``.. image:: dirname/filename.png``.
The available format tokens are:
* ``{root}`` - the filename, including any path component, without the file
extension, e.g. ``dirname/filename``
* ``{path}`` - the directory path component of the filename, with a trailing
slash if non-empty, e.g. ``dirname/``
* ``{docpath}`` - the directory path component for the current document, with
a trailing slash if non-empty.
* ``{basename}`` - the filename without the directory path or file extension
components, e.g. ``filename``
* ``{ext}`` - the file extension, e.g. ``.png``
* ``{language}`` - the translation language, e.g. ``en``
For example, setting this to ``{path}{language}/{basename}{ext}`` will
expand to ``dirname/en/filename.png`` instead.
.. versionadded:: 1.4
.. versionchanged:: 1.5
Added ``{path}`` and ``{basename}`` tokens.