forked from sphinx-doc/sphinx
/
CHANGES
3596 lines (2972 loc) · 156 KB
/
CHANGES
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
Release 1.8.0 (in development)
==============================
Dependencies
------------
Incompatible changes
--------------------
* #4460: extensions which stores any data to environment should return the
version of its env data structure as metadata. In detail, please see
:ref:`ext-metadata`.
* Sphinx expects source parser modules to have supported file formats as
``Parser.supported`` attribute
* The default value of :confval:`epub_author` and :confval:`epub_publisher` are
changed from ``'unknown'`` to the value of :confval:`author`. This is same as
a ``conf.py`` file sphinx-build generates.
* The ``gettext_compact`` attribute is removed from ``document.settings``
object. Please use ``config.gettext_compact`` instead.
* The processing order on reading phase is changed. smart_quotes, sphinx
domains, :event:`doctree-read` event and versioning doctrees are invoked
earlier than so far. For more details, please read a description of
:py:meth:`.Sphinx.add_transform()`
* #4827: All ``substitution_definition`` nodes are removed from doctree on
reading phase
* ``docutils.conf`` on ``$HOME`` and ``/etc`` directories are ignored. Only
``docutils.conf`` on confdir is refered.
* #789: ``:samp:`` role supports to escape curly braces with backslash
* #4811: The files under :confval:`html_static_path` are excluded from source
files.
* latex: Use ``\sphinxcite`` for citation references instead ``\hyperref``
Deprecated
----------
* :confval:`source_parsers` is deprecated
* ``Application.import_object()`` is deprecated
* Drop function based directive support. For now, Sphinx only supports class
based directives.
* ``Sphinx.add_source_parser()`` has changed; the *suffix* argument has
been deprecated
* ``sphinx.util.docutils.directive_helper()`` is deprecated
* ``sphinx.cmdline`` is deprecated
* All ``env.update()``, ``env._read_serial()`` and ``env._read_parallel()`` are
deprecated
* ``sphinx.locale.l_()`` is deprecated
* #2157: helper function ``warn()`` for HTML themes is deprecated
* ``env._nitpick_ignore`` is deprecated
* ``app.override_domain()`` is deprecated
* ``app.add_stylesheet()`` is deprecated
* ``sphinx.versioning.prepare()`` is deprecated
* ``Config.__init__()`` has changed; the *dirname*, *filename* and *tags*
argument has been deprecated
* ``Config.check_types()`` is deprecated
* ``Config.check_unicode()`` is deprecated
* ``sphinx.application.CONFIG_FILENAME`` is deprecated
* ``highlightlang`` directive is deprecated
* ``env.read_doc()`` is deprecated
* ``sphinx.writers.latex.Table.caption_footnotetexts`` is deprecated
* ``sphinx.writers.latex.Table.header_footnotetexts`` is deprecated
* ``sphinx.writers.latex.LaTeXWriter.footnotestack`` is deprecated
* ``sphinx.writers.latex.LaTeXWriter.restrict_footnote()`` is deprecated
* ``sphinx.writers.latex.LaTeXWriter.unrestrict_footnote()`` is deprecated
* ``LaTeXWriter.bibitems`` is deprecated
For more details, see `deprecation APIs list
<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
Features added
--------------
* Add :event:`config-inited` event
* Add ``sphinx.config.Any`` to represent the config value accepts any type of
value
* :confval:`source_suffix` allows a mapping fileext to file types
* Add :confval:`author` as a configuration value
* #2852: imgconverter: Support to convert GIF to PNG
* ``sphinx-build`` command supports i18n console output
* Add ``app.add_message_catalog()`` and ``sphinx.locale.get_translations()`` to
support translation for 3rd party extensions
* helper function ``warning()`` for HTML themes is added
* Add ``Domain.enumerable_nodes`` to manage own enumerable nodes for domains
(experimental)
* Add a new keyword argument ``override`` to Application APIs
* LaTeX: new key ``'fvset'`` for :confval:`latex_elements`. For
XeLaTeX/LuaLaTeX its default sets ``fanvyvrb`` to use normal, not small,
fontsize in code-blocks (refs: #4793)
* Add :confval:`html_css_files` and :confval:`epub_css_files` for adding CSS
files from configuration
* #4834: Ensure set object descriptions are reproducible.
* #4828: Allow to override :confval:`numfig_format` partially. Full definition
is not needed.
* Improve warning messages during including (refs: #4818)
* LaTeX: separate customizability of :rst:role:`guilabel` and
:rst:role:`menuselection` (refs: #4830)
* Add ``Config.read()`` classmethod to create a new config object from
configuration file
* #4866: Wrap graphviz diagrams in ``<div>`` tag
* Add :event:`viewcode-find-source` event to viewcode extension.
Bugs fixed
----------
* i18n: message catalogs were reset on each initialization
* #4850: latex: footnote inside footnote was not rendered
Testing
--------
Features removed
----------------
* ``sphinx.ext.pngmath`` extension
Release 1.7.5 (in development)
==============================
Dependencies
------------
Incompatible changes
--------------------
Deprecated
----------
Features added
--------------
Bugs fixed
----------
* #4924: html search: Upper characters problem in any other languages
Testing
--------
Release 1.7.4 (released Apr 25, 2018)
=====================================
Bugs fixed
----------
* #4885, #4887: domains: Crashed with duplicated objects
* #4889: latex: sphinx.writers.latex causes recusrive import
Release 1.7.3 (released Apr 23, 2018)
=====================================
Bugs fixed
----------
* #4769: autodoc loses the first staticmethod parameter
* #4790: autosummary: too wide two column tables in PDF builds
* #4795: Latex customization via ``_templates/longtable.tex_t`` is broken
* #4789: imgconverter: confused by convert.exe of Windows
* #4783: On windows, Sphinx crashed when drives of srcdir and outdir are
different
* #4812: autodoc ignores type annotated variables
* #4817: wrong URLs on warning messages
* #4784: latex: :confval:`latex_show_urls` assigns incorrect footnote numbers if
hyperlinks exists inside substitutions
* #4837: latex with class memoir Error: Font command ``\sf`` is not supported
* #4803: latex: too slow in proportion to number of auto numbered footnotes
* #4838: htmlhelp: The entries in .hhp file is not ordered
* toctree directive tries to glob for URL having query_string
* #4871: html search: Upper characters problem in German
* #4717: latex: Compilation for German docs failed with LuaLaTeX and XeLaTeX
* #4459: duplicated labels detector does not work well in parallel build
* #4878: Crashed with extension which returns invalid metadata
Release 1.7.2 (released Mar 21, 2018)
=====================================
Incompatible changes
--------------------
* #4520: apidoc: folders with an empty __init__.py are no longer excluded from
TOC
Bugs fixed
----------
* #4669: sphinx.build_main and sphinx.make_main throw NameError
* #4685: autosummary emits meaningless warnings
* autodoc: crashed when invalid options given
* pydomain: always strip parenthesis if empty (refs: #1042)
* #4689: autosummary: unexpectedly strips docstrings containing "i.e."
* #4701: viewcode: Misplaced ``<div>`` in viewcode html output
* #4444: Don't require numfig to use :numref: on sections
* #4727: Option clash for package textcomp
* #4725: Sphinx does not work with python 3.5.0 and 3.5.1
* #4716: Generation PDF file with TexLive on Windows, file not found error
* #4574: vertical space before equation in latex
* #4720: message when an image is mismatched for builder is not clear
* #4655, #4684: Incomplete localization strings in Polish and Chinese
* #2286: Sphinx crashes when error is happens in rendering HTML pages
* #4688: Error to download remote images having long URL
* #4754: sphinx/pycode/__init__.py raises AttributeError
* #1435: qthelp builder should htmlescape keywords
* epub: Fix docTitle elements of toc.ncx is not escaped
* #4520: apidoc: Subpackage not in toc (introduced in 1.6.6) now fixed
* #4767: html: search highlighting breaks mathjax equations
Release 1.7.1 (released Feb 23, 2018)
=====================================
Deprecated
----------
* #4623: ``sphinx.build_main()`` is deprecated.
* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
been changed (Since 1.7.0)
* #4664: ``sphinx.ext.intersphinx.debug()`` is deprecated.
For more details, see `deprecation APIs list
<http://www.sphinx-doc.org/en/master/extdev/index.html#deprecated-apis>`_
Bugs fixed
----------
* #4608: epub: Invalid meta tag is generated
* #4260: autodoc: keyword only argument separator is not disappeared if it is
appeared at top of the argument list
* #4622: epub: :confval:`epub_scheme` does not effect to content.opf
* #4627: graphviz: Fit graphviz images to page
* #4617: quickstart: PROJECT_DIR argument is required
* #4623: sphinx.build_main no longer exists in 1.7.0
* #4615: The argument of ``sphinx.build`` has been changed in 1.7.0
* autosummary: The interface of ``sphinx.ext.autosummary.get_documenter()`` has
been changed
* #4630: Have order on msgids in sphinx.pot deterministic
* #4563: autosummary: Incorrect end of line punctuation detection
* #4577: Enumerated sublists with explicit start with wrong number
* #4641: A external link in TOC cannot contain "?" with ``:glob:`` option
* C++, add missing parsing of explicit casts and typeid in expression parsing.
* C++, add missing parsing of ``this`` in expression parsing.
* #4655: Fix incomplete localization strings in Polish
* #4653: Fix error reporting for parameterless ImportErrors
* #4664: Reading objects.inv fails again
* #4662: ``any`` refs with ``term`` targets crash when an ambiguity is
encountered
Release 1.7.0 (released Feb 12, 2018)
=====================================
Dependencies
------------
1.7.0b1
* Add ``packaging`` package
Incompatible changes
--------------------
1.7.0b1
* #3668: The arguments has changed of main functions for each command
* #3893: Unknown html_theme_options throw warnings instead of errors
* #3927: Python parameter/variable types should match classes, not all objects
* #3962: sphinx-apidoc now recognizes given directory as an implicit namespace
package when ``--implicit-namespaces`` option given, not subdirectories of
given directory.
* #3929: apidoc: Move sphinx.apidoc to sphinx.ext.apidoc
* #4226: apidoc: Generate new style makefile (make-mode)
* #4274: sphinx-build returns 2 as an exit code on argument error
* #4389: output directory will be created after loading extensions
* autodoc does not generate warnings messages to the generated document even if
:confval:`keep_warnings` is True. They are only emitted to stderr.
* shebang line is removed from generated conf.py
* #2557: autodoc: :confval:`autodoc_mock_imports` only mocks specified modules
with their descendants. It does not mock their ancestors. If you want to
mock them, please specify the name of ancestors explicitly.
* #3620: html theme: move DOCUMENTATION_OPTIONS to independent JavaScript file
(refs: #4295)
* #4246: Limit width of text body for all themes. Conifigurable via theme
options ``body_min_width`` and ``body_max_width``.
* #4771: apidoc: The ``exclude_patterns`` arguments are ignored if they are
placed just after command line options
1.7.0b2
* #4467: html theme: Rename ``csss`` block to ``css``
Deprecated
----------
1.7.0b1
* using a string value for :confval:`html_sidebars` is deprecated and only list
values will be accepted at 2.0.
* ``format_annotation()`` and ``formatargspec()`` is deprecated. Please use
``sphinx.util.inspect.Signature`` instead.
* ``sphinx.ext.autodoc.AutodocReporter`` is replaced by ``sphinx.util.docutils.
switch_source_input()`` and now deprecated. It will be removed in Sphinx-2.0.
* ``sphinx.ext.autodoc.add_documenter()`` and ``AutoDirective._register`` is now
deprecated. Please use ``app.add_autodocumenter()`` instead.
* ``AutoDirective._special_attrgetters`` is now deprecated. Please use
``app.add_autodoc_attrgetter()`` instead.
Features added
--------------
1.7.0b1
* C++, handle ``decltype(auto)``.
* #2406: C++, add proper parsing of expressions, including linking of identifiers.
* C++, add a ``cpp:expr`` role for inserting inline C++ expressions or types.
* C++, support explicit member instantiations with shorthand ``template`` prefix.
* C++, make function parameters linkable, like template params.
* #3638: Allow to change a label of reference to equation using
``math_eqref_format``
* Now :confval:`suppress_warnings` accepts following configurations:
- ``ref.python`` (ref: #3866)
* #3872: Add latex key to configure literal blocks caption position in PDF
output (refs #3792, #1723)
* In case of missing docstring try to retrieve doc from base classes (ref: #3140)
* #4023: Clarify error message when any role has more than one target.
* #3973: epub: allow to override build date
* #3972: epub: Sort manifest entries by filename
* #4052: viewcode: Sort before highlighting module code
* #1448: qthelp: Add new config value; :confval:`qthelp_namespace`
* #4140: html themes: Make body tag inheritable
* #4168: improve zh search with jieba
* HTML themes can set up default sidebars through ``theme.conf``
* #3160: html: Use ``<kdb>`` to represent ``:kbd:`` role
* #4212: autosummary: catch all exceptions when importing modules
* #4166: Add :confval:`math_numfig` for equation numbering by section (refs:
#3991, #4080). Thanks to Oliver Jahn.
* #4311: Let LaTeX obey :confval:`numfig_secnum_depth` for figures, tables, and
code-blocks
* #947: autodoc now supports ignore-module-all to ignore a module's ``__all__``
* #4332: Let LaTeX obey :confval:`math_numfig` for equation numbering
* #4093: sphinx-build creates empty directories for unknown targets/builders
* Add ``top-classes`` option for the ``sphinx.ext.inheritance_diagram``
extension to limit the scope of inheritance graphs.
* #4183: doctest: ``:pyversion:`` option also follows PEP-440 specification
* #4235: html: Add :confval:`manpages_url` to make manpage roles to hyperlinks
* #3570: autodoc: Do not display 'typing.' module for type hints
* #4354: sphinx-build now emits finish message. Builders can modify it through
``Builder.epilog`` attribute
* #4245: html themes: Add ``language`` to javascript vars list
* #4079: html: Add ``notranslate`` class to each code-blocks, literals and maths
to let Google Translate know they are not translatable
* #4137: doctest: doctest block is always highlighted as python console (pycon)
* #4137: doctest: testcode block is always highlighted as python
* #3998: text: Assign section numbers by default. You can control it using
:confval:`text_add_secnumbers` and :confval:`text_secnumber_suffix`
1.7.0b2
* #4271: sphinx-build supports an option called ``-j auto`` to adjust numbers of
processes automatically.
* Napoleon: added option to specify custom section tags.
Features removed
----------------
1.7.0b1
* Configuration variables
- html_use_smartypants
- latex_keep_old_macro_names
- latex_elements['footer']
* utility methods of ``sphinx.application.Sphinx`` class
- buildername (property)
- _display_chunk()
- old_status_iterator()
- status_iterator()
- _directive_helper()
* utility methods of ``sphinx.environment.BuildEnvironment`` class
- currmodule (property)
- currclass (property)
* epub2 builder
* prefix and colorfunc parameter for warn()
* ``sphinx.util.compat`` module
* ``sphinx.util.nodes.process_only_nodes()``
* LaTeX environment ``notice``, use ``sphinxadmonition`` instead
* LaTeX ``\sphinxstylethead``, use ``\sphinxstyletheadfamily``
* C++, support of function concepts. Thanks to mickk-on-cpp.
* Not used and previously not documented LaTeX macros ``\shortversion``
and ``\setshortversion``
Bugs fixed
----------
1.7.0b1
* #3882: Update the order of files for HTMLHelp and QTHelp
* #3962: sphinx-apidoc does not recognize implicit namespace packages correctly
* #4094: C++, allow empty template argument lists.
* C++, also hyperlink types in the name of declarations with qualified names.
* C++, do not add index entries for declarations inside concepts.
* C++, support the template disambiguator for dependent names.
* #4314: For PDF 'howto' documents, numbering of code-blocks differs from the
one of figures and tables
* #4330: PDF 'howto' documents have an incoherent default LaTeX tocdepth counter
setting
* #4198: autosummary emits multiple 'autodoc-process-docstring' event. Thanks
to Joel Nothman.
* #4081: Warnings and errors colored the same when building
* latex: Do not display 'Release' label if :confval:`release` is not set
1.7.0b2
* #4415: autodoc classifies inherited classmethods as regular methods
* #4415: autodoc classifies inherited staticmethods as regular methods
* #4472: DOCUMENTATION_OPTIONS is not defined
* #4491: autodoc: prefer _MockImporter over other importers in sys.meta_path
* #4490: autodoc: type annotation is broken with python 3.7.0a4+
* utils package is no longer installed
* #3952: apidoc: module header is too escaped
* #4275: Formats accepted by sphinx.util.i18n.format_date are limited
* #4493: recommonmark raises AttributeError if AutoStructify enabled
* #4209: intersphinx: In link title, "v" should be optional if target has no
version
* #4230: slowdown in writing pages with sphinx 1.6
* #4522: epub: document is not rebuilt even if config changed
1.7.0b3
* #4019: inheritance_diagram AttributeError stoping make process
* #4531: autosummary: methods are not treated as attributes
* #4538: autodoc: ``sphinx.ext.autodoc.Options`` has been moved
* #4539: autodoc emits warnings for partialmethods
* #4223: doctest: failing tests reported in wrong file, at wrong line
* i18n: message catalogs are not compiled if specific filenames are given for
``sphinx-build`` as arguments (refs: #4560)
* #4027: sphinx.ext.autosectionlabel now expects labels to be the same as they
are in the raw source; no smart quotes, nothig fancy.
* #4581: apidoc: Excluded modules still included
Testing
--------
1.7.0b1
* Add support for docutils 0.14
* Add tests for the ``sphinx.ext.inheritance_diagram`` extension.
Release 1.6.7 (released Feb 04, 2018)
=====================================
Bugs fixed
----------
* #1922: html search: Upper characters problem in French
* #4412: Updated jQuery version from 3.1.0 to 3.2.1
* #4438: math: math with labels with whitespace cause html error
* #2437: make full reference for classes, aliased with "alias of"
* #4434: pure numbers as link targets produce warning
* #4477: Build fails after building specific files
* #4449: apidoc: include "empty" packages that contain modules
* #3917: citation labels are tranformed to ellipsis
* #4501: graphviz: epub3 validation error caused if graph is not clickable
* #4514: graphviz: workaround for wrong map ID which graphviz generates
* #4525: autosectionlabel does not support parallel build
* #3953: Do not raise warning when there is a working intersphinx inventory
* #4487: math: ValueError is raised on parallel build. Thanks to jschueller.
* #2372: autosummary: invalid signatures are shown for type annotated functions
* #3942: html: table is not aligned to center even if ``:align: center``
Release 1.6.6 (released Jan 08, 2018)
=====================================
Features added
--------------
* #4181: autodoc: Sort dictionary keys when possible
* ``VerbatimHighlightColor`` is a new
:ref:`LaTeX 'sphinxsetup' <latexsphinxsetup>` key (refs: #4285)
* Easier customizability of LaTeX macros involved in rendering of code-blocks
* Show traceback if conf.py raises an exception (refs: #4369)
* Add :confval:`smartquotes` to disable smart quotes through ``conf.py``
(refs: #3967)
* Add :confval:`smartquotes_action` and :confval:`smartquotes_excludes`
(refs: #4142, #4357)
Bugs fixed
----------
* #4334: sphinx-apidoc: Don't generate references to non-existing files in TOC
* #4206: latex: reST label between paragraphs loses paragraph break
* #4231: html: Apply fixFirefoxAnchorBug only under Firefox
* #4221: napoleon depends on autodoc, but users need to load it manually
* #2298: automodule fails to document a class attribute
* #4099: C++: properly link class reference to class from inside constructor
* #4267: PDF build broken by Unicode U+2116 NUMERO SIGN character
* #4249: PDF output: Pygments error highlighting increases line spacing in
code blocks
* #1238: Support ``:emphasize-lines:`` in PDF output
* #4279: Sphinx crashes with pickling error when run with multiple processes and
remote image
* #1421: Respect the quiet flag in sphinx-quickstart
* #4281: Race conditions when creating output directory
* #4315: For PDF 'howto' documents, ``latex_toplevel_sectioning='part'`` generates
``\chapter`` commands
* #4214: Two todolist directives break sphinx-1.6.5
* Fix links to external option docs with intersphinx (refs: #3769)
* #4091: Private members not documented without :undoc-members:
Release 1.6.5 (released Oct 23, 2017)
=====================================
Features added
--------------
* #4107: Make searchtools.js compatible with pre-Sphinx1.5 templates
* #4112: Don't override the smart_quotes setting if it was already set
* #4125: Display reference texts of original and translated passages on
i18n warning message
* #4147: Include the exception when logging PO/MO file read/write
Bugs fixed
----------
* #4085: Failed PDF build from image in parsed-literal using ``:align:`` option
* #4100: Remove debug print from autodoc extension
* #3987: Changing theme from alabaster causes HTML build to fail
* #4096: C++, don't crash when using the wrong role type. Thanks to mitya57.
* #4070, #4111: crashes when the warning message contains format strings (again)
* #4108: Search word highlighting breaks SVG images
* #3692: Unable to build HTML if writing .buildinfo failed
* #4152: HTML writer crashes if a field list is placed on top of the document
* #4063: Sphinx crashes when labeling directive ``.. todolist::``
* #4134: [doc] :file:`docutils.conf` is not documented explicitly
* #4169: Chinese language doesn't trigger Chinese search automatically
* #1020: ext.todo todolist not linking to the page in pdflatex
* #3965: New quickstart generates wrong SPHINXBUILD in Makefile
* #3739: ``:module:`` option is ignored at content of pyobjects
* #4149: Documentation: Help choosing :confval:`latex_engine`
* #4090: [doc] :confval:`latex_additional_files` with extra LaTeX macros should
not use ``.tex`` extension
* Failed to convert reST parser error to warning (refs: #4132)
Release 1.6.4 (released Sep 26, 2017)
=====================================
Features added
--------------
* #3926: Add ``autodoc_warningiserror`` to suppress the behavior of ``-W``
option during importing target modules on autodoc
Bugs fixed
----------
* #3924: docname lost after dynamically parsing RST in extension
* #3946: Typo in sphinx.sty (this was a bug with no effect in default context)
* :pep: and :rfc: does not supports ``default-role`` directive (refs: #3960)
* #3960: default_role = 'guilabel' not functioning
* Missing ``texinputs_win/Makefile`` to be used in latexpdf builder on windows.
* #4026: nature: Fix macOS Safari scrollbar color
* #3877: Fix for C++ multiline signatures.
* #4006: Fix crash on parallel build
* #3969: private instance attributes causes AttributeError
* #4041: C++, remove extra name linking in function pointers.
* #4038: C, add missing documentation of ``member`` role.
* #4044: An empty multicolumn cell causes extra row height in PDF output
* #4049: Fix typo in output of sphinx-build -h
* #4062: hashlib.sha1() must take bytes, not unicode on Python 3
* Avoid indent after index entries in latex (refs: #4066)
* #4070: crashes when the warning message contains format strings
* #4067: Return non-zero exit status when make subprocess fails
* #4055: graphviz: the :align: option does not work for SVG output
* #4055: graphviz: the :align: center option does not work for latex output
* #4051: ``warn()`` function for HTML theme outputs 'None' string
Release 1.6.3 (released Jul 02, 2017)
=====================================
Features added
--------------
* latex: hint that code-block continues on next page (refs: #3764, #3792)
Bugs fixed
----------
* #3821: Failed to import sphinx.util.compat with docutils-0.14rc1
* #3829: sphinx-quickstart template is incomplete regarding use of alabaster
* #3772: 'str object' has no attribute 'filename'
* Emit wrong warnings if citation label includes hyphens (refs: #3565)
* #3858: Some warnings are not colored when using --color option
* #3775: Remove unwanted whitespace in default template
* #3835: sphinx.ext.imgmath fails to convert SVG images if project directory
name contains spaces
* #3850: Fix color handling in make mode's help command
* #3865: use of self.env.warn in sphinx extension fails
* #3824: production lists apply smart quotes transform since Sphinx 1.6.1
* latex: fix ``\sphinxbfcode`` swallows initial space of argument
* #3878: Quotes in auto-documented class attributes should be straight quotes
in PDF output
* #3881: LaTeX figure floated to next page sometimes leaves extra vertical
whitespace
* #3885: duplicated footnotes raises IndexError
* #3873: Failure of deprecation warning mechanism of
``sphinx.util.compat.Directive``
* #3874: Bogus warnings for "citation not referenced" for cross-file citations
* #3860: Don't download images when builders not supported images
* #3860: Remote image URIs without filename break builders not supported remote
images
* #3833: command line messages are translated unintentionally with ``language``
setting.
* #3840: make checking ``epub_uid`` strict
* #3851, #3706: Fix about box drawing characters for PDF output
* #3900: autosummary could not find methods
* #3902: Emit error if ``latex_documents`` contains non-unicode string in py2
Release 1.6.2 (released May 28, 2017)
=====================================
Incompatible changes
--------------------
* #3789: Do not require typing module for python>=3.5
Bugs fixed
----------
* #3754: HTML builder crashes if HTML theme appends own stylesheets
* #3756: epub: Entity 'mdash' not defined
* #3758: Sphinx crashed if logs are emitted in conf.py
* #3755: incorrectly warns about dedent with literalinclude
* #3742: `RTD <https://readthedocs.org/>`_ PDF builds of Sphinx own docs are
missing an index entry in the bookmarks and table of contents. This is
`rtfd/readthedocs.org#2857
<https://github.com/rtfd/readthedocs.org/issues/2857>`_ issue, a workaround
is obtained using some extra LaTeX code in Sphinx's own :file:`conf.py`
* #3770: Build fails when a "code-block" has the option emphasize-lines and the
number indicated is higher than the number of lines
* #3774: Incremental HTML building broken when using citations
* #3763: got epubcheck validations error if epub_cover is set
* #3779: 'ImportError' in sphinx.ext.autodoc due to broken 'sys.meta_path'.
Thanks to Tatiana Tereshchenko.
* #3796: env.resolve_references() crashes when non-document node given
* #3803: Sphinx crashes with invalid PO files
* #3791: PDF "continued on next page" for long tables isn't internationalized
* #3788: smartquotes emits warnings for unsupported languages
* #3807: latex Makefile for ``make latexpdf`` is only for unixen
* #3781: double hyphens in option directive are compiled as endashes
* #3817: latex builder raises AttributeError
Release 1.6.1 (released May 16, 2017)
=====================================
Dependencies
------------
1.6b1
* (updated) latex output is tested with Ubuntu trusty's texlive packages (Feb.
2014) and earlier tex installations may not be fully compliant, particularly
regarding Unicode engines xelatex and lualatex
* (added) latexmk is required for ``make latexpdf`` on GNU/Linux and Mac OS X
(refs: #3082)
Incompatible changes
--------------------
1.6b1
* #1061, #2336, #3235: Now generation of autosummary doesn't contain imported
members by default. Thanks to Luc Saffre.
* LaTeX ``\includegraphics`` command isn't overloaded: only ``\sphinxincludegraphics``
has the custom code to fit image to available width if oversized.
* The subclasses of ``sphinx.domains.Index`` should override ``generate()``
method. The default implementation raises NotImplementedError
* LaTeX positioned long tables horizontally centered, and short ones
flushed left (no text flow around table.) The position now defaults to center in
both cases, and it will obey Docutils 0.13 ``:align:`` option (refs #3415, #3377)
* option directive also allows all punctuations for the option name (refs: #3366)
* #3413: if :rst:dir:`literalinclude`'s ``:start-after:`` is used, make ``:lines:``
relative (refs #3412)
* ``literalinclude`` directive does not allow the combination of ``:diff:``
option and other options (refs: #3416)
* LuaLaTeX engine uses ``fontspec`` like XeLaTeX. It is advised ``latex_engine
= 'lualatex'`` be used only on up-to-date TeX installs (refs #3070, #3466)
* :confval:`latex_keep_old_macro_names` default value has been changed from
``True`` to ``False``. This means that some LaTeX macros for styling are
by default defined only with ``\sphinx..`` prefixed names. (refs: #3429)
* Footer "Continued on next page" of LaTeX longtable's now not framed (refs: #3497)
* #3529: The arguments of ``BuildEnvironment.__init__`` is changed
* #3082: Use latexmk for pdf (and dvi) targets (Unix-like platforms only)
* #3558: Emit warnings if footnotes and citations are not referenced. The
warnings can be suppressed by ``suppress_warnings``.
* latex made available (non documented) colour macros from a file distributed
with pdftex engine for Plain TeX. This is removed in order to provide better
support for multiple TeX engines. Only interface from ``color`` or
``xcolor`` packages should be used by extensions of Sphinx latex writer.
(refs #3550)
* ``Builder.env`` is not filled at instantiation
* #3594: LaTeX: single raw directive has been considered as block level element
* #3639: If ``html_experimental_html5_writer`` is available, epub builder use it by default.
* ``Sphinx.add_source_parser()`` raises an error if duplicated
1.6b2
* #3345: Replace the custom smartypants code with Docutils' smart_quotes.
Thanks to Dmitry Shachnev, and to Günter Milde at Docutils.
1.6b3
* LaTeX package ``eqparbox`` is not used and not loaded by Sphinx anymore
* LaTeX package ``multirow`` is not used and not loaded by Sphinx anymore
* Add line numbers to citation data in std domain
1.6 final
* LaTeX package ``threeparttable`` is not used and not loaded by Sphinx
anymore (refs #3686, #3532, #3377)
Features removed
----------------
* Configuration variables
- epub3_contributor
- epub3_description
- epub3_page_progression_direction
- html_translator_class
- html_use_modindex
- latex_font_size
- latex_paper_size
- latex_preamble
- latex_use_modindex
- latex_use_parts
* ``termsep`` node
* defindex.html template
* LDML format support in `today`, `today_fmt` and `html_last_updated_fmt`
* ``:inline:`` option for the directives of sphinx.ext.graphviz extension
* sphinx.ext.pngmath extension
* ``sphinx.util.compat.make_admonition()``
Features added
--------------
1.6b1
* #3136: Add ``:name:`` option to the directives in ``sphinx.ext.graphviz``
* #2336: Add ``imported_members`` option to ``sphinx-autogen`` command to document
imported members.
* C++, add ``:tparam-line-spec:`` option to templated declarations.
When specified, each template parameter will be rendered on a separate line.
* #3359: Allow sphinx.js in a user locale dir to override sphinx.js from Sphinx
* #3303: Add ``:pyversion:`` option to the doctest directive.
* #3378: (latex) support for ``:widths:`` option of table directives
(refs: #3379, #3381)
* #3402: Allow to suppress "download file not readable" warnings using
:confval:`suppress_warnings`.
* #3377: latex: Add support for Docutils 0.13 ``:align:`` option for tables
(but does not implement text flow around table).
* latex: footnotes from inside tables are hyperlinked (except from captions or
headers) (refs: #3422)
* Emit warning if over dedent has detected on ``literalinclude`` directive
(refs: #3416)
* Use for LuaLaTeX same default settings as for XeLaTeX (i.e. ``fontspec`` and
``polyglossia``). (refs: #3070, #3466)
* Make ``'extraclassoptions'`` key of ``latex_elements`` public (refs #3480)
* #3463: Add warning messages for required EPUB3 metadata. Add default value to
``epub_description`` to avoid warning like other settings.
* #3476: setuptools: Support multiple builders
* latex: merged cells in LaTeX tables allow code-blocks, lists, blockquotes...
as do normal cells (refs: #3435)
* HTML builder uses experimental HTML5 writer if ``html_experimental_html5_writer`` is True
and docutils 0.13 or later is installed.
* LaTeX macros to customize space before and after tables in PDF output (refs #3504)
* #3348: Show decorators in literalinclude and viewcode directives
* #3108: Show warning if :start-at: and other literalinclude options does not
match to the text
* #3609: Allow to suppress "duplicate citation" warnings using
``suppress_warnings``
* #2803: Discovery of builders by entry point
* #1764, #1676: Allow setting 'rel' and 'title' attributes for stylesheets
* #3589: Support remote images on non-HTML builders
* #3589: Support images in Data URI on non-HTML builders
* #2961: improve :confval:`autodoc_mock_imports`. Now the config value only
requires to declare the top-level modules that should be mocked.
Thanks to Robin Jarry.
* #3449: On py3, autodoc use inspect.signature for more accurate signature
calculation. Thanks to Nathaniel J. Smith.
* #3641: Epub theme supports HTML structures that are generated by HTML5 writer.
* #3644 autodoc uses inspect instead of checking types. Thanks to
Jeroen Demeyer.
* Add a new extension; ``sphinx.ext.imgconverter``. It converts images in the
document to appropriate format for builders
* latex: Use templates to render tables (refs #3389, 2a37b0e)
1.6b2
* ``LATEXMKOPTS`` variable for the Makefile in ``$BUILDDIR/latex`` to pass
options to ``latexmk`` when executing ``make latexpdf`` (refs #3695, #3720)
* Add a new event `env-check-consistency` to check consistency to extensions
* Add `Domain.check_consistency()` to check consistency
Bugs fixed
----------
1.6b1
* ``literalinclude`` directive expands tabs after dedent-ing (refs: #3416)
* #1574: Paragraphs in table cell doesn't work in Latex output
* #3288: Table with merged headers not wrapping text
* #3491: Inconsistent vertical space around table and longtable in PDF
* #3506: Depart functions for all admonitions in HTML writer now properly pass ``node`` to ``depart_admonition``.
* #2693: Sphinx latex style file wrongly inhibits colours for section headings
for latex+dvi(ps,pdf,pdfmx)
* C++, properly look up ``any`` references.
* #3624: sphinx.ext.intersphinx couldn't load inventories compressed with gzip
* #3551: PDF information dictionary is lacking author and title data
* #3351: intersphinx does not refers context like ``py:module``, ``py:class``
and so on.
* Fail to load template file if the parent template is archived
1.6b2
* #3661: sphinx-build crashes on parallel build
* #3669: gettext builder fails with "ValueError: substring not found"
* #3660: Sphinx always depends on sphinxcontrib-websupport and its dependencies
* #3472: smart quotes getting wrong in latex (at least with list of strings via
autoattribute) (refs: #3345, #3666)
1.6b3
* #3588: No compact (p tag) html output in the i18n document build even when
:confval:`html_compact_lists` is True.
* The ``make latexpdf`` from 1.6b1 (for GNU/Linux and Mac OS, using
``latexmk``) aborted earlier in case of LaTeX errors than was the case with
1.5 series, due to hard-coded usage of ``--halt-on-error`` option. (refs #3695)
* #3683: sphinx.websupport module is not provided by default
* #3683: Failed to build document if builder.css_file.insert() is called
* #3714: viewcode extension not taking ``highlight_code='none'`` in account
* #3698: Moving :doc: to std domain broke backwards compatibility
* #3633: misdetect unreferenced citations
1.6 final
* LaTeX tables do not allow multiple paragraphs in a header cell
* LATEXOPTS is not passed over correctly to pdflatex since 1.6b3
* #3532: Figure or literal block captions in cells of short tables cause havoc
in PDF output
* Fix: in PDF captions of tables are rendered differently whether table is of
longtable class or not (refs #3686)
* #3725: Todo looks different from note in LaTeX output
* #3479: stub-columns have no effect in LaTeX output
* #3738: Nonsensical code in theming.py
* #3746: PDF builds fail with latexmk 4.48 or earlier due to undefined
options ``-pdfxe`` and ``-pdflua``
Deprecated
----------
1.6b1
* ``sphinx.util.compat.Directive`` class is now deprecated. Please use instead
``docutils.parsers.rst.Directive``
* ``sphinx.util.compat.docutils_version`` is now deprecated
* #2367: ``Sphinx.warn()``, ``Sphinx.info()`` and other logging methods are now
deprecated. Please use ``sphinx.util.logging`` (:ref:`logging-api`) instead.
* #3318: ``notice`` is now deprecated as LaTeX environment name and will be
removed at Sphinx 1.7. Extension authors please use ``sphinxadmonition``
instead (as Sphinx does since 1.5.)
* ``Sphinx.status_iterator()`` and ``Sphinx.old_status_iterator()`` is now
deprecated. Please use ``sphinx.util:status_iterator()`` instead.
* ``Sphinx._directive_helper()`` is deprecated. Please use
``sphinx.util.docutils.directive_helper()`` instead.
* ``BuildEnvironment.set_warnfunc()`` is now deprecated
* Following methods of ``BuildEnvironment`` is now deprecated.
- ``BuildEnvironment.note_toctree()``
- ``BuildEnvironment.get_toc_for()``
- ``BuildEnvironment.get_toctree_for()``
- ``BuildEnvironment.create_index()``
Please use ``sphinx.environment.adapters`` modules instead.
* latex package ``footnote`` is not loaded anymore by its bundled replacement
``footnotehyper-sphinx``. The redefined macros keep the same names as in the
original package.
* #3429: deprecate config setting ``latex_keep_old_macro_names``. It will be
removed at 1.7, and already its default value has changed from ``True`` to
``False``.
* #3221: epub2 builder is deprecated
* #3254: ``sphinx.websupport`` is now separated into independent package;
``sphinxcontrib-websupport``. ``sphinx.websupport`` will be removed in
Sphinx-2.0.
* #3628: ``sphinx_themes`` entry_point is deprecated. Please use
``sphinx.html_themes`` instead.
1.6b2
* #3662: ``builder.css_files`` is deprecated. Please use ``add_stylesheet()``
API instead.
1.6 final
* LaTeX ``\sphinxstylethead`` is deprecated at 1.6 and will be removed at 1.7.
Please move customization into new macro ``\sphinxstyletheadfamily``.
Testing
--------
1.6 final
* #3458: Add ``sphinx.testing`` (experimental)
Release 1.6 (unreleased)
========================
* not released (because of package script error)
Release 1.5.6 (released May 15, 2017)
=====================================
Bugs fixed
----------
* #3614: Sphinx crashes with requests-2.5.0
* #3618: autodoc crashes with tupled arguments
* #3664: No space after the bullet in items of a latex list produced by Sphinx
* #3657: EPUB builder crashes if document startswith genindex exists
* #3588: No compact (p tag) html output in the i18n document build even when
:confval:`html_compact_lists` is True.
* #3685: AttributeError when using 3rd party domains
* #3702: LaTeX writer styles figure legends with a hard-coded ``\small``
* #3708: LaTeX writer allows irc scheme
* #3717: Stop enforcing that favicon's must be .ico
* #3731, #3732: Protect isenumclass predicate against non-class arguments
* #3320: Warning about reference target not being found for container types
* Misspelled ARCHIVEPREFIX in Makefile for latex build repertory
Release 1.5.5 (released Apr 03, 2017)
=====================================
Bugs fixed
----------
* #3597: python domain raises UnboundLocalError if invalid name given
* #3599: Move to new Mathjax CDN
Release 1.5.4 (released Apr 02, 2017)
=====================================
Features added
--------------
* #3470: Make genindex support all kinds of letters, not only Latin ones
Bugs fixed
----------
* #3445: setting ``'inputenc'`` key to ``\\usepackage[utf8x]{inputenc}`` leads
to failed PDF build
* EPUB file has duplicated ``nav.xhtml`` link in ``content.opf``
except first time build
* #3488: objects.inv has broken when ``release`` or ``version`` contain
return code
* #2073, #3443, #3490: gettext builder that writes pot files unless the content
are same without creation date. Thanks to Yoshiki Shibukawa.
* #3487: intersphinx: failed to refer options
* #3496: latex longtable's last column may be much wider than its contents
* #3507: wrong quotes in latex output for productionlist directive
* #3533: Moving from Sphinx 1.3.1 to 1.5.3 breaks LaTeX compilation of links
rendered as code
* #2665, #2607: Link names in C++ docfields, and make it possible for other domains.
* #3542: C++, fix parsing error of non-type template argument with template.
* #3065, #3520: python domain fails to recognize nested class
* #3575: Problems with pdflatex in a Turkish document built with sphinx has
reappeared (refs #2997, #2397)
* #3577: Fix intersphinx debug tool
* A LaTeX command such as ``\\large`` inserted in the title items of
:confval:`latex_documents` causes failed PDF build (refs #3551, #3567)
Release 1.5.3 (released Feb 26, 2017)
=====================================
Features added
--------------
* Support requests-2.0.0 (experimental) (refs: #3367)
* (latex) PDF page margin dimensions may be customized (refs: #3387)
* ``literalinclude`` directive allows combination of ``:pyobject:`` and
``:lines:`` options (refs: #3416)
* #3400: make-mode doesn't use subprocess on building docs
Bugs fixed
----------
* #3370: the caption of code-block is not picked up for translation