Source

sphinx / doc / config.rst

georg.brandl 186cf92 

Georg Brandl 094431c 

georg.brandl 186cf92 





georg.brandl 5518267 

georg.brandl 186cf92 

georg.brandl 78037f6 
georg.brandl 5518267 


georg.brandl 186cf92 
georg.brandl 5518267 
georg.brandl 186cf92 
georg.brandl 5518267 

georg.brandl ece3261 
georg.brandl 5518267 

Georg Brandl 5ea1e4f 

georg.brandl 186cf92 
georg.brandl 5518267 


georg.brandl f544f55 




georg.brandl 5518267 



georg.brandl 186cf92 
Georg Brandl 25e024b 




georg.brandl 186cf92 






Georg Brandl 326d478 
georg.brandl 186cf92 

georg.brandl 5518267 


georg.brandl cabeb6a 






georg.brandl 5518267 

georg.brandl 186cf92 
georg.brandl a2afdae 


georg.brandl 186cf92 


georg.brandl 4676358 
georg.brandl 186cf92 
georg.brandl 4676358 


Georg Brandl 774c5e6 
georg.brandl 4676358 


mq 0e4cfbf 
georg.brandl 186cf92 


Georg Brandl f0cae30 
georg.brandl 186cf92 
Georg Brandl 5463dcc 


Georg Brandl ebe4c7c 
Georg Brandl 5463dcc 

















georg.brandl 35c2fa9 





Georg Brandl 5463dcc 


georg.brandl 33e0296 







Georg Brandl 5463dcc 


georg.brandl 33e0296 








Georg Brandl 5463dcc 

georg.brandl 35c2fa9 






Georg Brandl b69ed14 

Georg Brandl 90ae82c 

georg.brandl 35c2fa9 






Georg Brandl fd8b360 

georg.brandl 35c2fa9 





Georg Brandl fd8b360 

georg.brandl 35c2fa9 
Georg Brandl a8bae92 







Georg Brandl 4baa02a 
Georg Brandl a8bae92 



Georg Brandl 9501e6a 
Georg Brandl 9c67ee0 






Georg Brandl af6ce4d 
Georg Brandl e80d27d 

Georg Brandl af6ce4d 
Georg Brandl e80d27d 

Georg Brandl af6ce4d 

Georg Brandl 494e382 
Georg Brandl af6ce4d 

Georg Brandl e80d27d 


georg.brandl 35c2fa9 

Georg Brandl a8bae92 

georg.brandl 35c2fa9 

Georg Brandl b69ed14 

georg.brandl 35c2fa9 

Georg Brandl f0cae30 
georg.brandl 35c2fa9 












Georg Brandl c67f32d 
mq 0e4cfbf 
Georg Brandl c67f32d 


Georg Brandl d91bf8e 


Georg Brandl c67f32d 
Georg Brandl 220b8f9 
Georg Brandl c67f32d 


Georg Brandl 220b8f9 


mq 0e4cfbf 
georg.brandl 35c2fa9 

mq 0e4cfbf 
georg.brandl 186cf92 





















georg.brandl 35f91f9 


georg.brandl 86027a7 


georg.brandl 35f91f9 




Georg Brandl df01f02 
Georg Brandl d911b84 
georg.brandl 70a4d6c 
Georg Brandl ff95740 
georg.brandl 70a4d6c 
georg.brandl 35f91f9 
Georg Brandl 028a685 
Georg Brandl 395eb66 
georg.brandl 75a0f59 
Georg Brandl 36ab67b 
Georg Brandl 0aa422b 
Georg Brandl 5268b4d 
Georg Brandl 028a685 
georg.brandl cb94b5c 
Georg Brandl ad7e715 
Georg Brandl cd18cd4 
Georg Brandl 770c428 
Georg Brandl 194750b 
Georg Brandl 0a49658 
Georg Brandl a6afcdb 
Georg Brandl 028a685 
georg.brandl 35f91f9 
georg.brandl 186cf92 










georg.brandl 35f91f9 

georg.brandl 186cf92 
georg.brandl d539975 






mq 0e4cfbf 
georg.brandl a37bd71 

Georg Brandl e54cafc 

georg.brandl a37bd71 
georg.brandl 0ea2d1b 
georg.brandl a37bd71 


georg.brandl 186cf92 








Georg Brandl 2e1ab15 
Georg Brandl 0ac6246 
georg.brandl 186cf92 


Georg Brandl 0ac6246 

georg.brandl 186cf92 
Georg Brandl c67f32d 









Georg Brandl a42828c 
georg.brandl 186cf92 
Georg Brandl a42828c 




Georg Brandl c67f32d 








Georg Brandl 9501e6a 
georg.brandl 4ca916f 

georg.brandl 186cf92 





Georg Brandl 0ac6246 

Georg Brandl 08c42db 






















Georg Brandl fd8b360 







georg.brandl 8b762e4 







georg.brandl e5cba7b 







georg.brandl 2531f8f 

georg.brandl c462b4e 






georg.brandl 2531f8f 
georg.brandl 6b17af6 








georg.brandl 186cf92 


georg.brandl 5518267 
Georg Brandl 08c42db 

georg.brandl 186cf92 

georg.brandl 340ce9c 


Georg Brandl 66b1402 


georg.brandl 186cf92 


georg.brandl f9832b8 
georg.brandl 35f91f9 
georg.brandl 186cf92 





Georg Brandl f5ea666 







mq 0e4cfbf 
georg.brandl 186cf92 


Georg Brandl ebe4c7c 






























georg.brandl b845257 

Georg Brandl ebe4c7c 

georg.brandl b845257 

Georg Brandl ebe4c7c 









georg.brandl 186cf92 





georg.brandl b845257 
georg.brandl f9832b8 
georg.brandl b845257 






Georg Brandl 3d6d3cb 











georg.brandl 251e68a 



Georg Brandl 3d6d3cb 


georg.brandl f9832b8 



georg.brandl 6162288 
georg.brandl f9832b8 
georg.brandl a4e7d7a 





georg.brandl 35f91f9 
georg.brandl 186cf92 


georg.brandl fe067ef 

Georg Brandl 275f2b1 





Georg Brandl e43ef31 






georg.brandl fe067ef 

georg.brandl 3b37a79 





georg.brandl 186cf92 
georg.brandl e15ef58 

Georg Brandl 0431ecb 

georg.brandl e15ef58 


Georg Brandl 71a85ea 






mq 0e4cfbf 
georg.brandl 4976feb 

georg.brandl ece3261 
Georg Brandl 5ea1e4f 
georg.brandl ece3261 

georg.brandl 4976feb 
Georg Brandl fb1b662 



Georg Brandl 773abd7 
Georg Brandl fb1b662 
georg.brandl e5cba7b 






Georg Brandl d1a5c52 







Georg Brandl fc3e0f4 














georg.brandl 186cf92 




Roland Meister 6422ce7 




Georg Brandl 6ac1f33 


Roland Meister 6422ce7 



Georg Brandl 6ac1f33 







Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 


Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 



Roland Meister 6422ce7 


Georg Brandl 6ac1f33 



Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 


Roland Meister 6422ce7 

Georg Brandl 6ac1f33 
Roland Meister 6422ce7 

Georg Brandl 6ac1f33 
Roland Meister 6422ce7 


Georg Brandl 6ac1f33 
Roland Meister 4ca9c13 

Roland Meister 6422ce7 


Georg Brandl 6ac1f33 

Roland Meister 6422ce7 
Roland Meister 62d16b8 





Roland Meister 34defff 





Roland Meister 6422ce7 
georg.brandl 4ca916f 

georg.brandl 186cf92 






georg.brandl bb02bfb 

georg.brandl a83df96 
georg.brandl 186cf92 
georg.brandl bb02bfb 





georg.brandl 0e14878 





Georg Brandl e8c542b 




georg.brandl a83df96 






georg.brandl 186cf92 
georg.brandl 2531f8f 


georg.brandl 5518267 

georg.brandl 2531f8f 
georg.brandl b6a98f1 




georg.brandl 0ea2d1b 
georg.brandl b6a98f1 
georg.brandl 186cf92 

georg.brandl f544f55 
georg.brandl 186cf92 
Georg Brandl 3d6d3cb 










georg.brandl 4368135 



Georg Brandl 3d6d3cb 


Georg Brandl c3a4ec6 













georg.brandl 4368135 










mq 0e4cfbf 
georg.brandl 4368135 




















georg.brandl 6a4f0a6 

mq 0e4cfbf 
georg.brandl 4368135 
mq 0e4cfbf 
georg.brandl 4368135 
georg.brandl 6a4f0a6 

georg.brandl 4368135 





georg.brandl 6a4f0a6 






mq 0e4cfbf 
georg.brandl 4368135 
mq 0e4cfbf 
georg.brandl 4368135 









mq 0e4cfbf 
Georg Brandl 5b1718f 







Georg Brandl 16a84dc 












georg.brandl 186cf92 


georg.brandl 251e68a 
georg.brandl 4368135 

georg.brandl f544f55 
georg.brandl 4368135 
georg.brandl 251e68a 
georg.brandl 4368135 










Georg Brandl 5463dcc 

Georg Brandl 2ffdb09 





















Georg Brandl 54f9372 


Georg Brandl 2ffdb09 





Georg Brandl 5463dcc 

Georg Brandl ebe4c7c 
Georg Brandl 5463dcc 

   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
.. highlightlang:: python

.. _build-config:

The build configuration file
============================

.. 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 all configuration needed to customize Sphinx input and output behavior.

The configuration file is executed as Python code at build time (using
:func:`execfile`, 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: declare the encoding using an encoding cookie
  (a comment like ``# -*- coding: utf-8 -*-``) and use Unicode string literals
  when you include non-ASCII characters in configuration values.

* 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.

* 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.


General configuration
---------------------

.. confval:: extensions

   A list of strings that are module names of Sphinx extensions.  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 name extension of source files.  Only files with this suffix will be
   read as sources.  Default is ``'.rst'``.

.. 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:: master_doc

   The document name of the "master" document, that is, the document that
   contains the root :rst:dir:`toctree` directive.  Default is ``'contents'``.

.. confval:: exclude_patterns

   A list of glob-style patterns that should be excluded when looking for source
   files. [1]_ 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 (replaces
     entry in :confval:`unused_docs`
   - ``'library/xml'`` -- ignores the ``library/xml`` directory (replaces entry
     in :confval:`exclude_trees`)
   - ``'library/xml*'`` -- ignores all files and directories starting with
     ``library/xml``
   - ``'**/.svn'`` -- ignores all ``.svn`` directories (replaces entry in
     :confval:`exclude_dirnames`)

   :confval:`exclude_patterns` is also consulted when looking for static files
   in :confval:`html_static_path`.

   .. versionadded:: 1.0

.. confval:: unused_docs

   A list of document names that are present, but not currently included in the
   toctree.  Use this setting to suppress the warning that is normally emitted
   in that case.

   .. deprecated:: 1.0
      Use :confval:`exclude_patterns` instead.

.. confval:: exclude_trees

   A list of directory paths, relative to the source directory, that are to be
   recursively excluded from the search for source files, that is, their
   subdirectories won't be searched too.  The default is ``[]``.

   .. versionadded:: 0.4

   .. deprecated:: 1.0
      Use :confval:`exclude_patterns` instead.

.. confval:: exclude_dirnames

   A list of directory names that are to be excluded from any recursive
   operation Sphinx performs (e.g. searching for source files or copying static
   files).  This is useful, for example, to exclude version-control-specific
   directories like ``'CVS'``.  The default is ``[]``.

   .. versionadded:: 0.5

   .. deprecated:: 1.0
      Use :confval:`exclude_patterns` instead.

.. confval:: locale_dirs

   .. versionadded:: 0.5

   Directories in which to search for additional Sphinx message catalogs (see
   :confval:`language`), relative to the source directory.  The directories on
   this path are searched by the standard :mod:`gettext` module for a text
   domain of ``sphinx``; so if you add the directory :file:`./locale` to this
   settting, the message catalogs (compiled from ``.po`` format using
   :program:`msgfmt`) must be in
   :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.

   The default is ``[]``.

.. 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.

.. 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 the right place to add substitutions that should
   be available in every file.  An example::

      rst_epilog = """
      .. |psf| replace:: Python Software Foundation
      """

   .. versionadded:: 0.6

.. confval:: rst_prolog

   A string of reStructuredText that will be included at the beginning of every
   source file that is read.

   .. versionadded:: 1.0

.. confval:: primary_domain

   .. index:: default; domain
              primary; domain

   The name of the default :ref:`domain <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 :rst:dir:`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:: 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

.. 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` command-line switch.

   .. versionadded:: 1.0


Project information
-------------------

.. confval:: project

   The documented project's name.

.. confval:: copyright

   A copyright statement in the style ``'2008, Author Name'``.

.. 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.

.. confval:: language

   The code for the language the docs are written in.  Any text automatically
   generated by Sphinx will be in that language.  Also, in the LaTeX builder, a
   suitable language will be selected as an option for the *Babel* package.
   Default is ``None``, which means that no translation will be done.

   .. versionadded:: 0.5

   Currently supported languages are:

   * ``bn`` -- Bengali
   * ``ca`` -- Catalan
   * ``cs`` -- Czech
   * ``da`` -- Danish
   * ``de`` -- German
   * ``en`` -- English
   * ``es`` -- Spanish
   * ``fi`` -- Finnish
   * ``fr`` -- French
   * ``hr`` -- Croatian
   * ``it`` -- Italian
   * ``lt`` -- Lithuanian
   * ``nl`` -- Dutch
   * ``pl`` -- Polish
   * ``pt_BR`` -- Brazilian Portuguese
   * ``ru`` -- Russian
   * ``sl`` -- Slovenian
   * ``tr`` -- Turkish
   * ``uk_UA`` -- Ukrainian
   * ``zh_CN`` -- Simplified Chinese
   * ``zh_TW`` -- Traditional Chinese

.. 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 no :confval:`today` and a :confval:`today_fmt` of ``'%B %d,
   %Y'`` (or, if translation is enabled with :confval:`language`, am equivalent
   %format for the selected locale).

.. confval:: highlight_language

   The default language to highlight source code in.  The default is
   ``'python'``.  The value should be a valid Pygments lexer name, see
   :ref:`code-examples` for more details.

   .. versionadded:: 0.5

.. confval:: pygments_style

   The style name to use for Pygments highlighting of source code.  The default
   style is selected by the theme for HTML output, and ``'sphinx'`` otherwise.

   .. 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:: 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:: 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 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


.. _html-options:

Options for HTML output
-----------------------

These options influence HTML as well as HTML Help output, and other builders
that use Sphinx' HTMLWriter class.

.. XXX document html_context

.. confval:: html_theme

   The "theme" that the HTML output should use.  See the :doc:`section about
   theming <theming>`.  The default is ``'default'``.

   .. versionadded:: 0.6

.. confval:: html_theme_options

   A dictionary of options that influence the look and feel of the selected
   theme.  These are theme-specific.  For the options understood by the builtin
   themes, see :ref:`this section <builtin-themes>`.

   .. versionadded:: 0.6

.. confval:: html_theme_path

   A list of paths that contain custom themes, either as subdirectories or as
   zip files.  Relative paths are taken as relative to the configuration
   directory.

   .. versionadded:: 0.6

.. confval:: html_style

   The style sheet to use for HTML pages.  A file of that name must exist either
   in Sphinx' :file:`static/` path, or in one of the custom paths given in
   :confval:`html_static_path`.  Default is the stylesheet given by the selected
   theme.  If you only want to add or override a few things compared to the
   theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet.

.. confval:: html_title

   The "title" for HTML documentation generated with Sphinx' own templates.
   This is appended to the ``<title>`` tag of individual pages, and used in the
   navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
   v{<revision>} documentation'`, where the placeholders are replaced by the
   config values of the same name.

.. confval:: html_short_title

   A shorter "title" for the HTML docs.  This is used in for links in the header
   and in the HTML Help docs.  If not given, it defaults to the value of
   :confval:`html_title`.

   .. versionadded:: 0.4

.. confval:: html_logo

   If given, this must be the name of an image file that is the logo of the
   docs.  It is placed at the top of the sidebar; its width should therefore not
   exceed 200 pixels.  Default: ``None``.

   .. versionadded:: 0.4.1
      The image file will be copied to the ``_static`` directory of the output
      HTML, so an already existing file with that name will be overwritten.

.. confval:: html_favicon

   If given, this must be the name of an image file (within the static path, see
   below) that is the favicon of the docs.  Modern browsers use this as icon for
   tabs, windows and bookmarks.  It should be a Windows-style icon file
   (``.ico``), which is 16x16 or 32x32 pixels large.  Default: ``None``.

   .. versionadded:: 0.4

.. confval:: html_static_path

   A list of paths that contain custom static files (such as style sheets or
   script files).  Relative paths are taken as relative to the configuration
   directory.  They are copied to the output directory after the theme's static
   files, so a file named :file:`default.css` will overwrite the theme's
   :file:`default.css`.

   .. versionchanged:: 0.4
      The paths in :confval:`html_static_path` can now contain subdirectories.

   .. versionchanged:: 1.0
      The entries in :confval:`html_static_path` can now be single files.

.. confval:: html_last_updated_fmt

   If this is not the empty string, a 'Last updated on:' timestamp is inserted
   at every page bottom, using the given :func:`strftime` format.  Default is
   ``'%b %d, %Y'`` (or a locale-dependent equivalent).

.. confval:: html_use_smartypants

   If true, *SmartyPants* will be used to convert quotes and dashes to
   typographically correct entities.  Default: ``True``.

.. confval:: html_add_permalinks

   If true, Sphinx will add "permalinks" for each heading and description
   environment as paragraph signs that become visible when the mouse hovers over
   them.  Default: ``True``.

   .. versionadded:: 0.6
      Previously, this was always activated.

.. confval:: html_sidebars

   Custom sidebar templates, must be a dictionary that maps document names to
   template names.

   The keys can contain glob-style patterns [1]_, in which case all matching
   documents will get the specified sidebars.  (A warning is emitted when a
   more than one glob-style pattern matches for any document.)

   The values can be either lists or single strings.

   * If a value is a list, it specifies the complete list of sidebar templates
     to include.  If all or some of the default sidebars are to be included,
     they must be put into this list as well.

     The default sidebars (for documents that don't match any pattern) are:
     ``['localtoc.html', 'relations.html', 'sourcelink.html',
     'searchbox.html']``.

   * If a value is a single string, it specifies a custom sidebar to be added
     between the ``'sourcelink.html'`` and ``'searchbox.html'`` entries.  This
     is for compatibility with Sphinx versions before 1.0.

   Builtin sidebar templates that can be rendered are:

   * **localtoc.html** -- a fine-grained table of contents of the current document
   * **globaltoc.html** -- a coarse-grained table of contents for the whole
     documentation set, collapsed
   * **relations.html** -- two links to the previous and next documents
   * **sourcelink.html** -- a link to the source of the current document, if
     enabled in :confval:`html_show_sourcelink`
   * **searchbox.html** -- the "quick search" box

   Example::

      html_sidebars = {
         '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
         'using/windows': ['windowssidebar.html', 'searchbox.html'],
      }

   This will render the custom template ``windowssidebar.html`` and the quick
   search box within the sidebar of the given document, and render the default
   sidebars for all other pages (except that the local TOC is replaced by the
   global TOC).

   .. versionadded:: 1.0
      The ability to use globbing keys and to specify multiple sidebars.

   Note that this value only has no effect if the chosen theme does not possess
   a sidebar, like the builtin **scrolls** and **haiku** themes.

.. confval:: html_additional_pages

   Additional templates that should be rendered to HTML pages, must be a
   dictionary that maps document names to template names.

   Example::

      html_additional_pages = {
          'download': 'customdownload.html',
      }

   This will render the template ``customdownload.html`` as the page
   ``download.html``.

.. confval:: html_domain_indices

   If true, generate domain-specific indices in addition to the general index.
   For e.g. the Python domain, this is the global module index.  Default is
   ``True``.

   This value can be a bool or a list of index names that should be generated.
   To find out the index name for a specific index, look at the HTML file name.
   For example, the Python module index has the name ``'py-modindex'``.

   .. versionadded:: 1.0

.. confval:: html_use_modindex

   If true, add a module index to the HTML documents.   Default is ``True``.

   .. deprecated:: 1.0
      Use :confval:`html_domain_indices`.

.. confval:: html_use_index

   If true, add an index to the HTML documents.  Default is ``True``.

   .. versionadded:: 0.4

.. confval:: html_split_index

   If true, the index is generated twice: once as a single page with all the
   entries, and once as one page per starting letter.  Default is ``False``.

   .. versionadded:: 0.4

.. confval:: html_copy_source

   If true, the reST sources are included in the HTML build as
   :file:`_sources/{name}`.  The default is ``True``.

   .. warning::

      If this config value is set to ``False``, the JavaScript search function
      will only display the titles of matching documents, and no excerpt from
      the matching contents.

.. confval:: html_show_sourcelink

   If true (and :confval:`html_copy_source` is true as well), links to the
   reST sources will be added to the sidebar.  The default is ``True``.

   .. versionadded:: 0.6

.. confval:: html_use_opensearch

   If nonempty, an `OpenSearch <http://opensearch.org>` description file will be
   output, and all pages will contain a ``<link>`` tag referring to it.  Since
   OpenSearch doesn't support relative URLs for its search page location, the
   value of this option must be the base URL from which these documents are
   served (without trailing slash), e.g. ``"http://docs.python.org"``.  The
   default is ``''``.

.. confval:: html_file_suffix

   This is the file name suffix for generated HTML files.  The default is
   ``".html"``.

   .. versionadded:: 0.4

.. confval:: html_link_suffix

   Suffix for generated links to HTML files.  The default is whatever
   :confval:`html_file_suffix` is set to; it can be set differently (e.g. to
   support different web server setups).

   .. versionadded:: 0.6

.. confval:: html_translator_class

   A string with the fully-qualified name of a HTML Translator class, that is, a
   subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used
   to translate document trees to HTML.  Default is ``None`` (use the builtin
   translator).

.. confval:: html_show_copyright

   If true, "(C) Copyright ..." is shown in the HTML footer. Default is ``True``.

   .. versionadded:: 1.0

.. confval:: html_show_sphinx

   If true, "Created using Sphinx" is shown in the HTML footer.  Default is
   ``True``.

   .. versionadded:: 0.4

.. confval:: html_output_encoding

   Encoding of HTML output files. Default is ``'utf-8'``.  Note that this
   encoding name must both be a valid Python encoding name and a valid HTML
   ``charset`` value.

   .. versionadded:: 1.0

.. confval:: html_compact_lists

   If true, list items containing only a single paragraph will not be rendered
   with a ``<p>`` element.  This is standard docutils behavior.  Default:
   ``True``.

   .. versionadded:: 1.0

.. confval:: html_secnumber_suffix

   Suffix for section numbers.  Default: ``". "``.  Set to ``" "`` to suppress
   the final dot on section numbers.

   .. versionadded:: 1.0

.. confval:: htmlhelp_basename

   Output file base name for HTML help builder.  Default is ``'pydoc'``.


.. _epub-options:

Options for epub output
-----------------------

These options influence the epub output.  As this builder derives from the HTML
builder, the HTML options also apply where appropriate.  The actual values for
some of the options is not really important, they just have to be entered into
the `Dublin Core metadata <http://dublincore.org/>`_.

.. confval:: epub_basename

   The basename for the epub file.  It defaults to the :confval:`project` name.

.. confval:: epub_theme

   The HTML theme for the epub output.  Since the default themes are not
   optimized for small screen space, using the same theme for HTML and epub
   output is usually not wise.  This defaults to ``'epub'``, a theme designed to
   save visual space.

.. confval:: epub_title

   The title of the document.  It defaults to the :confval:`html_title` option
   but can be set independently for epub creation.

.. confval:: epub_author

   The author of the document.  This is put in the Dublin Core metadata.  The
   default value is ``'unknown'``.

.. confval:: epub_language

   The language of the document.  This is put in the Dublin Core metadata.  The
   default is the :confval:`language` option or ``'en'`` if unset.

.. confval:: epub_publisher

   The publisher of the document.  This is put in the Dublin Core metadata.  You
   may use any sensible string, e.g. the project homepage.  The default value is
   ``'unknown'``.

.. confval:: epub_copyright

   The copyright of the document.  It defaults to the :confval:`copyright`
   option but can be set independently for epub creation.

.. confval:: epub_identifier

   An identifier for the document.  This is put in the Dublin Core metadata.
   For published documents this is the ISBN number, but you can also use an
   alternative scheme, e.g. the project homepage.  The default value is
   ``'unknown'``.

.. confval:: epub_scheme

   The publication scheme for the :confval:`epub_identifier`.  This is put in
   the Dublin Core metadata.  For published books the scheme is ``'ISBN'``.  If
   you use the project homepage, ``'URL'`` seems reasonable.  The default value
   is ``'unknown'``.

.. confval:: epub_uid

   A unique identifier for the document.  This is put in the Dublin Core
   metadata.  You may use a random string.  The default value is ``'unknown'``.

.. confval:: epub_pre_files

   Additional files that should be inserted before the text generated by
   Sphinx. It is a list of tuples containing the file name and the title.
   Example::

      epub_pre_files = [
          ('index.html', 'Welcome'),
      ]

   The default value is ``[]``.

.. confval:: epub_post_files

   Additional files that should be inserted after the text generated by Sphinx.
   It is a list of tuples containing the file name and the title.  This option
   can be used to add an appendix.  The default value is ``[]``.

.. confval:: epub_exclude_files

   A list of files that are generated/copied in the build directory but should
   not be included in the epub file.  The default value is ``[]``.

.. confval:: epub_tocdepth

   The depth of the table of contents in the file :file:`toc.ncx`.  It should
   be an integer greater than zero.  The default value is 3.  Note: A deeply
   nested table of contents may be difficult to navigate.

.. confval:: epub_tocdup

   This flag determines if a toc entry is inserted again at the beginning of
   it's nested toc listing.  This allows easier navitation to the top of
   a chapter, but can be confusing because it mixes entries of differnet
   depth in one list.  The default value is ``True``.

.. _latex-options:

Options for LaTeX output
------------------------

These options influence LaTeX output.

.. confval:: latex_documents

   This value determines how to group the document tree into LaTeX source files.
   It must be a list of tuples ``(startdocname, targetname, title, author,
   documentclass, toctree_only)``, where the items are:

   * *startdocname*: document name that is the "root" of the LaTeX file.  All
     documents referenced by it in TOC trees will be included in the LaTeX file
     too.  (If you want only one LaTeX file, use your :confval:`master_doc`
     here.)
   * *targetname*: file name of the LaTeX file in the output directory.
   * *title*: LaTeX document title.  Can be empty to use the title of the
     *startdoc*.  This is inserted as LaTeX markup, so special characters like a
     backslash or ampersand must be represented by the proper LaTeX commands if
     they are to be inserted literally.
   * *author*: Author for the LaTeX document.  The same LaTeX markup caveat as
     for *title* applies.  Use ``\and`` to separate multiple authors, as in:
     ``'John \and Sarah'``.
   * *documentclass*: Normally, one of ``'manual'`` or ``'howto'`` (provided by
     Sphinx).  Other document classes can be given, but they must include the
     "sphinx" package in order to define Sphinx' custom LaTeX commands.
     "howto" documents will not get appendices.  Also, howtos will have a simpler
     title page.
   * *toctree_only*: Must be ``True`` or ``False``.  If ``True``, the *startdoc*
     document itself is not included in the output, only the documents
     referenced by it via TOC trees.  With this option, you can put extra stuff
     in the master document that shows up in the HTML, but not the LaTeX output.

   .. versionadded:: 0.3
      The 6th item ``toctree_only``.  Tuples with 5 items are still accepted.

.. confval:: latex_logo

   If given, this must be the name of an image file (relative to the
   configuration directory) that is the logo of the docs.  It is placed at the
   top of the title page.  Default: ``None``.

.. confval:: latex_use_parts

   If true, the topmost sectioning unit is parts, else it is chapters.  Default:
   ``False``.

   .. versionadded:: 0.3

.. confval:: latex_appendices

   A list of document names to append as an appendix to all manuals.

.. confval:: latex_domain_indices

   If true, generate domain-specific indices in addition to the general index.
   For e.g. the Python domain, this is the global module index.  Default is
   ``True``.

   This value can be a bool or a list of index names that should be generated,
   like for :confval:`html_domain_indices`.

   .. versionadded:: 1.0

.. confval:: latex_use_modindex

   If true, add a module index to LaTeX documents.   Default is ``True``.

   .. deprecated:: 1.0
      Use :confval:`latex_domain_indices`.

.. confval:: latex_show_pagerefs

   If true, add page references after internal references.  This is very useful
   for printed copies of the manual.  Default is ``False``.

   .. versionadded:: 1.0

.. confval:: latex_show_urls

   If true, add URL addresses after links.  This is very useful for printed
   copies of the manual.  Default is ``False``.

   .. versionadded:: 1.0

.. confval:: latex_elements

   .. versionadded:: 0.5

   A dictionary that contains LaTeX snippets that override those Sphinx usually
   puts into the generated ``.tex`` files.

   Keep in mind that backslashes must be doubled in Python string literals to
   avoid interpretation as escape sequences.

   * Keys that you may want to override include:

     ``'papersize'``
        Paper size option of the document class (``'a4paper'`` or
        ``'letterpaper'``), default ``'letterpaper'``.
     ``'pointsize'``
        Point size option of the document class (``'10pt'``, ``'11pt'`` or
        ``'12pt'``), default ``'10pt'``.
     ``'babel'``
        "babel" package inclusion, default ``'\\usepackage{babel}'``.
     ``'fontpkg'``
        Font package inclusion, default ``'\\usepackage{times}'`` (which uses
        Times and Helvetica).  You can set this to ``''`` to use the Computer
        Modern fonts.
     ``'fncychap'``
        Inclusion of the "fncychap" package (which makes fancy chapter titles),
        default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation,
        ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because
        the "Bjarne" style uses numbers spelled out in English).  Other
        "fncychap" styles you can try include "Lenny", "Glenn", "Conny" and
        "Rejne".  You can also set this to ``''`` to disable fncychap.
     ``'preamble'``
        Additional preamble content, default empty.
     ``'footer'```
        Additional footer content (before the indices), default empty.

   * Keys that don't need be overridden unless in special cases are:

     ``'inputenc'``
        "inputenc" package inclusion, default
        ``'\\usepackage[utf8]{inputenc}'``.
     ``'fontenc'``
        "fontenc" package inclusion, default ``'\\usepackage[T1]{fontenc}'``.
     ``'maketitle'``
        "maketitle" call, default ``'\\maketitle'``.  Override if you want to
        generate a differently-styled title page.
     ``'tableofcontents'``
        "tableofcontents" call, default ``'\\tableofcontents'``.  Override if
        you want to generate a different table of contents or put content
        between the title page and the TOC.
     ``'printindex'``
        "printindex" call, the last thing in the file, default
        ``'\\printindex'``.  Override if you want to generate the index
        differently or append some content after the index.

   * Keys that are set by other options and therefore should not be overridden are:

     ``'docclass'``
     ``'classoptions'``
     ``'title'``
     ``'date'``
     ``'release'``
     ``'author'``
     ``'logo'``
     ``'releasename'``
     ``'makeindex'``
     ``'shorthandoff'``

.. confval:: latex_docclass

   A dictionary mapping ``'howto'`` and ``'manual'`` to names of real document
   classes that will be used as the base for the two Sphinx classes.  Default
   is to use ``'article'`` for ``'howto'`` and ``'report'`` for ``'manual'``.

   .. versionadded:: 1.0

.. confval:: latex_additional_files

   A list of file names, relative to the configuration directory, to copy to the
   build directory when building LaTeX output.  This is useful to copy files
   that Sphinx doesn't copy automatically, e.g. if they are referenced in custom
   LaTeX added in ``latex_elements``.  Image files that are referenced in source
   files (e.g. via ``.. image::``) are copied automatically.

   You have to make sure yourself that the filenames don't collide with those of
   any automatically copied files.

   .. versionadded:: 0.6

.. confval:: latex_preamble

   Additional LaTeX markup for the preamble.

   .. deprecated:: 0.5
      Use the ``'preamble'`` key in the :confval:`latex_elements` value.

.. confval:: latex_paper_size

   The output paper size (``'letter'`` or ``'a4'``).  Default is ``'letter'``.

   .. deprecated:: 0.5
      Use the ``'papersize'`` key in the :confval:`latex_elements` value.

.. confval:: latex_font_size

   The font size ('10pt', '11pt' or '12pt'). Default is ``'10pt'``.

   .. deprecated:: 0.5
      Use the ``'pointsize'`` key in the :confval:`latex_elements` value.


.. _man-options:

Options for manual page output
------------------------------

These options influence manual page output.

.. confval:: man_pages

   This value determines how to group the document tree into manual pages.  It
   must be a list of tuples ``(startdocname, name, description, authors,
   section)``, where the items are:

   * *startdocname*: document name that is the "root" of the manual page.  All
     documents referenced by it in TOC trees will be included in the manual file
     too.  (If you want one master manual page, use your :confval:`master_doc`
     here.)
   * *name*: name of the manual page.  This should be a short string without
     spaces or special characters.  It is used to determine the file name as
     well as the name of the manual page (in the NAME section).
   * *description*: description of the manual page.  This is used in the NAME
     section.
   * *authors*: A list of strings with authors, or a single string.  Can be
     an empty string or list if you do not want to automatically generate
     an AUTHORS section in the manual page.
   * *section*: The manual page section.  Used for the output file name as well
     as in the manual page header.

   .. versionadded:: 1.0


.. rubric:: Footnotes

.. [1] 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.