Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add changelog entry for docutils 0.18 support #1389

Merged
merged 2 commits into from Dec 15, 2022
Merged

Add changelog entry for docutils 0.18 support #1389

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
91770b4
Add changelog entry for docutils 0.18 support
benjaoming Dec 15, 2022
a85c8a1
Update docs/changelog.rst
benjaoming Dec 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/changelog.rst
View file
Open in desktop
Expand Up @@ -9,6 +9,21 @@ Development version (|development_version|)

.. |development_version| replace:: 1.1.2alpha1

Dependency Changes
------------------

* docutils 0.18 is supported. (#1381)

Note for users of Sphinx<3
--------------------------

If you have pinned your documentation project to use versions of
``sphinx<1.8.6`` or ``Sphinx>=2.0,<2.4.5``, you need to either
add ``docutils<0.18`` to your requirements since newer versions of docutils are incompatible with these older Sphinx versions
**or**
update to a later release of Sphinx that has docutils correctly pinned.
Read more in `this comment <https://github.com/readthedocs/sphinx_rtd_theme/pull/1304#issuecomment-1266924478>`.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For the future, basically no one looks at the changelog, so I don't like to spend much time here. But, at this point we should always guide users toward upgrading. There is a lot of Technically Correctness in the suggestion here that I think we can just skip entirely, and make our guidance "just upgrade Sphinx".

Suggested change
If you have pinned your documentation project to use versions of
``sphinx<1.8.6`` or ``Sphinx>=2.0,<2.4.5``, you need to either
add ``docutils<0.18`` to your requirements since newer versions of docutils are incompatible with these older Sphinx versions
**or**
update to a later release of Sphinx that has docutils correctly pinned.
Read more in `this comment <https://github.com/readthedocs/sphinx_rtd_theme/pull/1304#issuecomment-1266924478>`.
If you cannot use a more recent Sphinx release,
you should at least ensure you are using the most recent release for your major version.
Currently, these are Sphinx `1.8.6` and `2.4.5`.
Older releases may install unsupported versions of several dependencies, including Jinja2 and docutils.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

basically no one looks at the changelog

The ones that do have a good reason :)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aye, and for anything major we should put this information somewhere more accessible, but agreed that for cases like this it's nice to have some artifact.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a good "read more" reference for blog posts and toots 👍


.. _release-1.1.1:

1.1.1
Expand Down