You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Note when I upgrade things to sphinx 4, I will consider dropping support for sphinx 2. I think that's reasonable, to support the latest 2 version of sphinx (FYI 3.0.0 was released Apr 06, 2020)
cc @choldgraf@mmcky
Release 4.0.0 beta1 (released Apr 12, 2021)
===========================================
Dependencies
------------* Drop python 3.5 support
* Drop docutils 0.12 and 0.13 support
* LaTeX: add ``tex-gyre`` font dependency
Incompatible changes
--------------------*#8539: autodoc: info-field-list is generated into the class description when
``autodoc_typehints='description'`` and ``autoclass_content='class'`` set
*#8898: extlinks: "%s" becomes required keyword in the link caption string
* domain: The ``Index`` class becomes subclasses of ``abc.ABC`` to indicate
methods that must be overrided in the concrete classes
*#4826: py domain: The structure of python objects is changed. A boolean value
is added to indicate that the python object is canonical one
*#7425: MathJax: The MathJax was changed from 2 to 3. Users using a custom
MathJax configuration may have to set the old MathJax path or update their
configuration for version 3. See :mod:`sphinx.ext.mathjax`.
*#7784: i18n: The msgid for alt text of image is changed
*#5560: napoleon: :confval:`napoleon_use_param` also affect "other parameters"
section
*#7996: manpage: Make a section directory on build manpage by default (see
:confval:`man_make_section_directory`)
*#7849: html: Change the default setting of
:confval:`html_codeblock_linenos_style` to ``'inline'``*#8380: html search: search results are wrapped with ``<p>`` instead of
``<div>``* html theme: Move a script tag for documentation_options.js in
basic/layout.html to ``script_files`` variable
* html theme: Move CSS tags in basic/layout.html to ``css_files`` variable
*#8915: html theme: Emit a warning for sphinx_rtd_theme-0.2.4 or older
*#8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese
documents
*#5977: py domain: ``:var:``, ``:cvar:`` and ``:ivar:`` fields do not create
cross-references
*#4550: The ``align`` attribute of ``figure`` and ``table`` nodes becomes
``None`` by default instead of ``'default'``*#8769: LaTeX refactoring: split sphinx.sty into multiple files and rename
some auxiliary files created in ``latex`` build output repertory
*#8937: Use explicit title instead of <notitle>
*#8487: The :file: option for csv-table directive now recognizes an absolute
path as a relative path from source directory
Deprecated
----------* :confval:`html_codeblock_linenos_style`*``favicon`` and ``logo`` variable in HTML templates
*``sphinx.directives.patches.CSVTable``*``sphinx.directives.patches.ListTable``*``sphinx.directives.patches.RSTTable``*``sphinx.ext.autodoc.directive.DocumenterBridge.filename_set``*``sphinx.ext.autodoc.directive.DocumenterBridge.warn()``*``sphinx.registry.SphinxComponentRegistry.get_source_input()``*``sphinx.registry.SphinxComponentRegistry.source_inputs``*``sphinx.transforms.FigureAligner``*``sphinx.util.pycompat.convert_with_2to3()``*``sphinx.util.pycompat.execfile_()``*``sphinx.util.smartypants``*``sphinx.util.typing.DirectiveOption``
Features added
--------------*#8924: autodoc: Support ``bound`` argument for TypeVar
*#7383: autodoc: Support typehints for properties
*#5603: autodoc: Allow to refer to a python class using its canonical name
when the class has two different names; a canonical name and an alias name
*#8539: autodoc: Add :confval:`autodoc_typehints_description_target` to control
the behavior of ``autodoc_typehints=description``*#8841: autodoc: :confval:`autodoc_docstring_signature` will continue to look
for multiple signature lines without backslash character
*#7549: autosummary: Enable :confval:`autosummary_generate` by default
*#8898: extlinks: Allow %s in link caption string
*#4826: py domain: Add ``:canonical:`` option to python directives to describe
the location where the object is defined
*#7199: py domain: Add :confval:`python_use_unqualified_type_names` to suppress
the module name of the python reference if it can be resolved (experimental)
*#7068: py domain: Add :rst:dir:`py:property` directive to describe a property
*#7784: i18n: The alt text for image is translated by default (without
:confval:`gettext_additional_targets` setting)
*#2018: html: :confval:`html_favicon` and :confval:`html_logo` now accept URL
for the image
*#8070: html search: Support searching for 2characters word
*#9036: html theme: Allow to inherite the search page
*#8938: imgconverter: Show the error of the command availability check
*#7830: Add debug logs for change detection of sources and templates
*#8201: Emit a warning if toctree contains duplicated entries
*#8326: ``master_doc`` is now renamed to :confval:`root_doc`*#8942: C++, add support for the C++20 spaceship operator, ``<=>``.
*#7199: A new node, ``sphinx.addnodes.pending_xref_condition`` has been added.
It can be used to choose appropriate content of the reference by conditions.
Bugs fixed
----------*#8917: autodoc: Raises a warning if function has wrong __globals__ value
*#8415: autodoc: a TypeVar imported from other module is not resolved (in
Python 3.7 or above)
*#8992: autodoc: Failed to resolve types.TracebackType type annotation
*#8905: html: html_add_permalinks=None and html_add_permalinks="" are ignored
*#8380: html search: Paragraphs in search results are not identified as ``<p>``*#8915: html theme: The translation of sphinx_rtd_theme does not work
*#8342: Emit a warning if a unknown domain is given for directive or role (ex.
``:unknown:doc:``)
*#7241: LaTeX: No wrapping for ``cpp:enumerator``*#8711: LaTeX: backticks in code-blocks trigger latexpdf build warning (and font
change) with late TeXLive 2019
*#8253: LaTeX: Figures with no size defined get overscaled (compared to images
with size explicitly set in pixels) (fixed for ``'pdflatex'/'lualatex'`` only)
*#8881: LaTeX: The depth of bookmarks panel in PDF is not enough for navigation
*#8874: LaTeX: the fix to two minor Pygments LaTeXFormatter output issues ignore
Pygments style
*#8925: LaTeX: 3.5.0 ``verbatimmaxunderfull`` setting does not work as
expected
*#8980: LaTeX: missing line break in ``\pysigline``*#8995: LaTeX: legacy ``\pysiglinewithargsret`` does not compute correctly
available horizontal space and should use a ragged right style
*#9009: LaTeX: "release" value with underscore leads to invalid LaTeX
*#8911: C++: remove the longest matching prefix in
:confval:`cpp_index_common_prefix` instead of the first that matches.
* C, properly reject function declarations when a keyword is used
as parameter name.
*#8933: viewcode: Failed to create back-links on parallel build
*#8960: C and C++, fix rendering of (member) function pointer types in
function parameter lists.
* C++, fix linking of names in array declarators, pointer to member
(function) declarators, and in the argument to ``sizeof...``.
* C, fix linking of names in array declarators.
If we are only going to support the last two versions of sphinx we should document this as an EBP practice. Cc the @executablebooks/ebpteam to see if anyone has a big objection
I am fine with it - it's going to be a big burden if we must support many major versions
But this would not preclude people using older versions of the EBP packages, if people do want to still use sphinx 2.
These projects though have had over a year now to update to sphinx 3, so I am skeptical if they ever will (without a nudge) 😬 Perhaps it would be helpful if you could list some of the packages that you feel are important but do not yet support sphinx 3?
Activity
chrisjsewell commentedon Apr 11, 2021
thanks @Daltz333, I will move this to meta, as a general TODO for all the EPB sphinx based repos
welcome commentedon Apr 11, 2021
Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! 🎉
chrisjsewell commentedon Apr 11, 2021
Release plan issue here: sphinx-doc/sphinx#9056
chrisjsewell commentedon Apr 27, 2021
Note when I upgrade things to sphinx 4, I will consider dropping support for sphinx 2. I think that's reasonable, to support the latest 2 version of sphinx (FYI 3.0.0 was released Apr 06, 2020)
cc @choldgraf @mmcky
chrisjsewell commentedon Apr 27, 2021
For reference:
chrisjsewell commentedon Apr 27, 2021
One thing that will definitely need changing in myst-parser:
mathjax_configto:confval:
mathjax2_configand add :confval:mathjax3_configcholdgraf commentedon Apr 27, 2021
If we are only going to support the last two versions of sphinx we should document this as an EBP practice. Cc the @executablebooks/ebpteam to see if anyone has a big objection
I am fine with it - it's going to be a big burden if we must support many major versions
Daltz333 commentedon Apr 27, 2021
Sphinx 2 is actually the main version of Sphinx for a huge number of packages. So I'm supportive of the past two. So 4-3-2, no 1. Then 5,4,3
chrisjsewell commentedon Apr 27, 2021
But this would not preclude people using older versions of the EBP packages, if people do want to still use sphinx 2.
These projects though have had over a year now to update to sphinx 3, so I am skeptical if they ever will (without a nudge) 😬 Perhaps it would be helpful if you could list some of the packages that you feel are important but do not yet support sphinx 3?
choldgraf commentedon Apr 27, 2021
*removed because the plot wasn't showing what I thought it was
hukkin commentedon Apr 28, 2021
choldgraf commentedon Apr 28, 2021
Ahh yes you're right @hukkinj1 , I always misinterpret those plots. Will remove it to reduce noise.
choldgraf commentedon Apr 28, 2021
OK better link - here's a plot of actual Sphinx version installs (I think 😅)
https://pepy.tech/project/sphinx?versions=3.5.4&versions=4.0.0b1&versions=2.4.4&versions=2.3.1&versions=1.8.5
Funnily enough, it's about 80% Sphinx 3 and Sphinx 1 has more installs than Sphinx 2 (my guess is legacy enterprise deployments and such).
So I think that this is still a decent suggestion that it's OK to deprecate Sphinx 2 support, IMO.
astrojuanlu commentedon Apr 29, 2021
astrojuanlu commentedon Apr 29, 2021
astrojuanlu commentedon Apr 29, 2021
jpmckinney commentedon May 11, 2021
1.8.5 is probably so high because for a long time it was the default version installed by ReadTheDocs.