Update docs (major) #231

renovate · 2025-04-08T18:22:54Z

This PR contains the following updates:

Package	Type	Update	Change
myst-parser	dependencies	major	`>=0.13` -> `>=4.0.1`
myst_parser		major	`>=0.13` -> `>=4.0.1`
sphinx (source)	dependencies	major	`>=7.0` -> `>=8.2.3`
sphinx (changelog)		major	`>=7.0` -> `>=8.2.3`
sphinx-autodoc-typehints (source)	dependencies	major	`*` -> `>=3.1.0`

Release Notes

ExecutableBookProject/MyST-Parser (myst-parser)

`v4.0.1`

🔧 Minor fix for Sphinx 8.2 compatibility (in gh-pr:1013)

`v4.0.0`

This release bumps the supported versions of:

Python to 3.10 and greater
Sphinx to >=7,<9
Docutils to >=0.19,<0.22

Additionally, footnotes are now parsed similar to the corresponding reStructuredText, in that resolution (between definitions and references) and ordering is now deferred to transforms on the doctree (in gh-pr:931).

This allows for the proper interaction with other docutils/sphinx transforms, including those that perform translations,
and logging of warnings for duplicate/unreferenced footnote definitions and also for footnote references with no definitions.

See the footnotes guide for more information.

Full Changelog: v3.0.1...v4.0.0

`v3.0.1`

🐛 Bug Fixes

Account for the final directive option having an empty value, by gh-user:chrisjsewell in gh-pr:924
Re-allow indented directive option blocks, by gh-user:chrisjsewell in gh-pr:925

Full Changelog: v3.0.0...v3.0.1

`v3.0.0`

Upgraded dependencies

⬆️ Add support for Python 3.12 by gh-user:hugovk in gh-pr:848
⬆️ Update docutils requirement from >=0.16,<0.21 to >=0.18,<0.22 by gh-user:chrisjsewell in gh-pr:916

New features

✨ Allow for use of the line-block directive by gh-user:chrisjsewell in gh-pr:900
✨ Emits sphinx include-read event by gh-user:sumezulike in gh-pr:887

Improvements

👌 Nested parse attribution in attr_block by gh-user:chrisjsewell in gh-pr:831
👌 Directive option parsing by gh-user:chrisjsewell in <gh-pr:796
👌 Improve directive parsing warnings by gh-user:chrisjsewell in gh-pr:893
👌 Allow for opening external links in new tabs (#856) by gh-user:marjus45 in gh-pr:857

Internal

🔧 Replace black, isort, pyupgrade with ruff formatter by gh-user:chrisjsewell in gh-pr:833
🔧 remove redundant mypy config by gh-user:danieleades in gh-pr:866
🔧 Add additional Ruff lints (and fix issues) by gh-user:danieleades in gh-pr:862
🔧 mypy- disallow 'any generics' by gh-user:danieleades in gh-pr:865
🔧 Fix docutils deprecation in option parsing by gh-user:agoose77 in gh-pr:842

Documentation

📚 Fix a broken link in configuration.md by gh-user:zupo in gh-pr:907
📚 Add linkify dependency to contributing docs. by gh-user:jhcole in gh-pr:792
📚 Fix the double used in docs/syntax/math.md by gh-user:ice-tong in gh-pr:810
📚 Also add linkify to pip install command in README by gh-user:n-peugnet in gh-pr:851
📚 Fix the code section title in live preview by gh-user:BoboTiG in gh-pr:875
📚 Fix admonition example by gh-user:72757373656c6c in gh-pr:904
📚 Fix url for jupyter book gallery by gh-user:72757373656c6c in gh-pr:905
📚 Update theme version by gh-user:chrisjsewell in gh-pr:918
📚 Fix typo by gh-user:blakeNaccarato in gh-pr:911
📚 Fix architecture typo (#855) by gh-user:72757373656c6c in gh-pr:910

Full Changelog: v2.0.0...v3.0.0

`v2.0.0`

This release primarily updates core myst-parser dependencies,
with some minor changes to parsing behaviour:

⬆️ UPGRADE: markdown-it-py to v3 (gh-pr:773)
- This is mainly a non-breaking change, fixing some edge cases in parsing
- See: https://github.com/executablebooks/markdown-it-py/releases/tag/v3.0.0
  and https://github.com/executablebooks/mdit-py-plugins/releases/tag/v0.4.0
⬆️ UPGRADE: linkify-it-py to v2 (gh-pr:675)
- Also fixes some edge cases in parsing
- See: https://github.com/tsutsu3/linkify-it-py/blob/main/CHANGELOG.md
⬆️ UPGRADE: Add support for docutils v0.20 (gh-pr:775)
- No significant changes, see https://docutils.sourceforge.io/RELEASE-NOTES.html#release-0-20-2023-05-04
⬆️ UPGRADE: Add support for sphinx v7, and remove v5 support (gh-pr:776)
- No significant changes, see https://www.sphinx-doc.org/en/master/changes/index.html
⬆️ UPGRADE: Remove Python 3.7 support and add testing for Python 3.11 (gh-pr:772)
👌 Improve default slug generation for heading anchors, thanks to gh-user:Cimbali (gh-pr:777)
- This change makes the slug generation closer to GitHub, in that, starting/ending whitespace will not be stripped.
  For example, # ` a` b `c ` will now correctly create the slug -a-b-c- and not a-b-c
👌 IMPROVE: Substitution extension (gh-pr:777)
- Allow any value type (including dict, list, datetime) and emit a myst.substitution warning for errors in resolving the substitution content.
🧪 Introduce a gate/check GHA job, thanks to gh-user:webknjaz (gh-pr:635)

Full Changelog: v1.0.0...v2.0.0

`v1.0.0`

🎉 MyST-Parser 1.0.0 🎉

This changes absolutely nothing in the code, or about the maintenance/release policy of this project.
But it does feel about time 😄

`v0.19.1`

🐛 FIX NoURI error in doc reference resolution, for texinfo builds (gh-pr:734)

`v0.18.1`

Full Changelog: v0.18.0...v0.18.1

⬆️ UPGRADE: docutils 0.19 support in gh-pr:611
✨ NEW: Add attrs_image (experimental) extension in gh-pr:620
- e.g. ![image](image.png){#id .class width=100px}
- See: Optional syntax section
- Important: This is an experimental extension, and may change in future releases

`v0.18.0`

Full Changelog: v0.17.2...v0.18.0

This release adds support for Sphinx v5 (dropping v3), restructures the code base into modules, and also restructures the documentation, to make it easier for developers/users to follow.

It also introduces document-level configuration via the Markdown front-matter, under the myst key.
See the Local configuration section for more information.

Breaking changes

This should not be breaking, for general users of the sphinx extension (with sphinx>3),
but will be for anyone directly using the Python API, mainly just requiring changes in import module paths.

The to_docutils, to_html, to_tokens (from myst_parser/main.py) and mock_sphinx_env/parse (from myst_parser.sphinx_renderer.py) functions have been removed, since these were primarily for internal testing.
Instead, for single page builds, users should use the docutils parser API/CLI (see ),
and for testing, functionality has been moved to https://github.com/chrisjsewell/sphinx-pytest.

The top-level html_meta and substitutions front-matter keys have also been deprecated (i.e. they will still work but will emit a warning), as they now form part of the myst config, e.g.

`v0.17.2`

Full Changelog: v0.17.1...v0.17.2

♻️ REFACTOR: Replace attrs by dataclasses for configuration (gh-pr:557)

`v0.17.0`

This release contains a number of breaking improvements.

Full Changelog: v0.16.1...v0.17.0

‼️ Markdown link resolution improvements

WARNING: This is a breaking change for links that rely on auto-generated anchor links. You should now manually enable auto-generated anchor links if you see errors like WARNING reference target not found.

Markdown links are of the format [text](link).
MyST-Parser looks to smartly resolve such links, by identifying if they are:

A link to an external resource, e.g. [text](http://example.com)
A link to another source document, e.g. [text](file.md)
- If header-anchors are enabled, anchor links are also supported, e.g. [text](file.md#anchor)
A link to an internal sphinx cross-reference, e.g. [text](my-reference)

an additional situation is now supported:

A link to a source file, which is not a document, e.g. [text](file.js). This behaves similarly to the sphinx download role.

In addition, configuration to more finely tune this behaviour has been added.

myst_all_links_external=True, will make all links be treated as (1)
myst_url_schemes=("http", "https"), sets what URL schemes are treated as (1)
myst_ref_domains=("std", "py"), sets what Sphinx reference domains are checked, when handling (3)

See Markdown Links and Referencing for more information.

‼️ Dollarmath is now disabled by default

WARNING: This is a breaking change for dollar math. You should now manually enable dollar math (see below).

The default configuration is now myst_enable_extensions=(), instead of myst_enable_extensions=("dollarmath",).
If you are using math enclosed in $ or $$ in your documents, you should enable dollarmath explicitly.

See Dollar delimited math for more information.

⬆️ Drop Python 3.6 support

MyST-Parser now supports, and is tested against, Python 3.7 to 3.10.

✨ Add the `strikethrough` extension and `myst_gfm_only` configuration

The strikethrough extension allows text within ~~ delimiters to have a strike-through (horizontal line) placed over it.
For example, ~~strikethrough with *emphasis*~~ renders as: strikethrough with emphasis.

Important: This extension is currently only supported for HTML output.

See Strikethrough for more information.

The myst_gfm_only=True configuration sets up specific configuration, to enable compliance only with GitHub-flavored Markdown, including enabling the strikethrough, tasklist and linkify extensions, but disabling support for roles and directives.

✨ Add `myst_title_to_header` configuration

Setting myst_title_to_header=True, allows for a title key in the frontmatter to be used as the document title.
for example:

`v0.16.1`

✨ NEW: Add myst_linkify_fuzzy_links option.
When using the linkify extension, this option can be used to disable matching of links that do not contain a schema (such as http://).

`v0.15.2`

This is mainly a maintenance release that fixes some incompatibilities with sphinx<3.1, improvements for compatibility
with docutils=0.17, and improvements to robustness.

`v0.15.1`

👌 IMPROVE: MathJax compatibility with nbsphinx

nbsphinx also overrides the MathJax configuration.
For compatibility, output_area is added to the list of default processed classes, and the override warning is allowed to be suppressed with suppress_warnings = ["myst.mathjax"].

`v0.15.0`

Upgraded to `sphinx` v4 ⬆️

A principe change in this release is to updates the requirements of myst-parser from sphinx>=2,<4 to sphinx>=3,<5.

Changed MathJax handling ♻️

Instead of removing all $ processing for the whole project,
during MyST document parsing, the top-level section is now given the classes tex2jax_ignore and mathjax_ignore (turning off default MathJax processing of all HTML elements)
and MathJax is then configured to process elements with the tex2jax_process|mathjax_process|math classes.

See the math syntax guide for further information.

Set URL scheme defaults ‼️

The myst_url_schemes default is now: ("http", "https", "mailto", "ftp").
This means that only these URL will be considered as external (e.g. [](https://example.com)),
and references like [](prefix:main) will be considered as internal references.
Set myst_url_schemes = None, to revert to the previous default.

Added `myst_heading_slug_func` option 👌

Use this option to specify a custom function to auto-generate heading anchors (see Auto-generated header anchors).

Thanks to gh-user:jpmckinney!

`v0.14.0`

Upgrade to `markdown-it-py` v1.0 ⬆️

This release updates the code-base to fully support the markdown-it-py v1.0.0 release.
In particular for users, this update alters the parsing of tables to be consistent with the Github Flavoured Markdown (GFM) specification.

New Features ✨

Task lists utilise the markdown-it-py tasklists plugin, and are applied to Markdown list items starting with [ ] or [x].
```
- [ ] An item that needs doing
- [x] An item that is complete
```
Add "tasklist" to the myst_enable_extensions configuration to enable.

See the optional syntax guide for further information.
The sub-ref role has been added for use identical to ReST's |name| syntax.

This allows one to access Sphinx's built-in |today|, |release| and |version| substitutions, and also introduces two new substitutions: wordcount-words and wordcount-minutes, computed by the markdown-it-py wordcount_plugin.
```
> {sub-ref}`today` | {sub-ref}`wordcount-words` words | {sub-ref}`wordcount-minutes` min read
```
See the roles syntax guide for further information.
The dmath_double_inline configuration option allows display math (i.e. $$) within an inline context.
See the math syntax guide for further information.

Remove v0.13 deprecations ‼️

The deprecations made to extension configurations and colon fences in 0.13.0 (see below) have now been removed:

Configuration variables: myst_admonition_enable, myst_figure_enable, myst_dmath_enable, myst_amsmath_enable, myst_deflist_enable, myst_html_img_enable
:::{admonition,class} -> :::{admonition}\n:class: class
:::{figure} -> :::{figure-md}

Fix extraction of nested footnotes 🐛

Previously footnote definitions in block elements like lists would crash the parsing:

- [^e]: footnote definition in a block element

These are now correctly extracted.

`v0.13.7`

👌 IMPROVE: Add warning for nested headers:

Nested headers are not supported within most elements (this is a limitation of the docutils/sphinx document structure), and can lead to unexpected outcomes.
For example in admonitions:

```{note}

`v0.13.5`

⬆️ UPGRADE: required markdown-it-py to v0.6.2:
In particular, this fixes missing source line mappings for table rows and their children
👌 IMPROVE: Store rawtext in AST nodes:
We now ensure that the raw text is propagated from the Markdown tokens to the Sphinx AST.
In particular, this is required by the gettext builder, to generate translation POT templates.
Thanks to gh-user:jpmckinney!
✨ NEW: Add warning types myst.subtype:
All parsing warnings are assigned a type/subtype, and also the messages are appended with them.
These warning types can be suppressed with the sphinx suppress_warnings config option.
See How-to suppress warnings for more information.

`v0.13.3`

Minor fixes:

🐛 FIX: front-matter parsing for bibliographic keys
🐛 FIX: directive/role name translations
👌 IMPROVE: Add warning for multiple footnote definitions

`v0.13.2`

✨ NEW: Add html_admonition extension

: By adding "html_admonition" to myst_enable_extensions, you can enable parsing of <div class="admonition"> HTML blocks to sphinx admonitions.
: This is helpful when you care about viewing the "source" Markdown, such as in Jupyter Notebooks.
: For example:

<div class="admonition note" name="html-admonition">
<p class="title">This is the **title**</p>
This is the *content*
</div>

: See the optional syntax guide for further information.

👌 IMPROVE: Footnotes

: If the label is an integer, then it will always use this integer for the rendered label (i.e. they are manually numbered).
: Add myst_footnote_transition configuration, to turn on/off transition line.
: Add footnotes class to transition <hr> in HTML.
: See the typography guide for further information.

👌 IMPROVE: substitution extension logic

: Parse inline substitutions without block rules, unless the substitution starts with a directive.

🐛 FIX: Render front-matter as field_list

: To improve use by sphinx extensions).

👌 IMPROVE: Code quality

: Add isort and mypy type checking to code base.

(thanks to contributors gh-user:akhmerov, gh-user:tfiers)

`v0.13.1`

👌 Directives can now be used for inline substitutions, e.g.

executablebooks/MyST-Parser (myst_parser)

Update docs (major) #231

Update docs (major) #231

Uh oh!

Conversation

renovate bot commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release Notes

🐛 Bug Fixes

Upgraded dependencies

New features

Improvements

Internal

Documentation

Breaking changes

‼️ Markdown link resolution improvements

‼️ Dollarmath is now disabled by default

⬆️ Drop Python 3.6 support

✨ Add the strikethrough extension and myst_gfm_only configuration

✨ Add myst_title_to_header configuration

Upgraded to sphinx v4 ⬆️

Changed MathJax handling ♻️

Set URL scheme defaults ‼️

Added myst_heading_slug_func option 👌

Upgrade to markdown-it-py v1.0 ⬆️

New Features ✨

Remove v0.13 deprecations ‼️

Fix extraction of nested footnotes 🐛

🐛 Bug Fixes

Upgraded dependencies

New features

Improvements

Internal

Documentation

📚 Rewritten documentation

⬆️ Add Sphinx 6 support, drop Sphinx 4

📄 Extended docutils (single-page) support

🔗 Extended Markdown links

{} Attributes syntax

👌 Miscellaneous improvements

Additional contributions

Breaking changes

‼️ Markdown link resolution improvements

‼️ Dollarmath is now disabled by default

⬆️ Drop Python 3.6 support

✨ Add the strikethrough extension and myst_gfm_only configuration

✨ Add myst_title_to_header configuration

Upgrade of Markdown parser

Upgraded to sphinx v4 ⬆️

Changed MathJax handling ♻️

Set URL scheme defaults ‼️

Added myst_heading_slug_func option 👌

Upgrade to markdown-it-py v1.0 ⬆️

New Features ✨

Remove v0.13 deprecations ‼️

Fix extraction of nested footnotes 🐛

v8.2.3: Sphinx 8.2.3

v8.2.2: Sphinx 8.2.2

v8.2.1: Sphinx 8.2.1

v8.2.0: Sphinx 8.2.0

Dependencies

Incompatible changes

Deprecated

Features added

Configuration

Uh oh!

renovate bot commented Apr 8, 2025

⚠️ Artifact update problem

File name: pixi.lock

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

renovate bot commented Apr 8, 2025 •

edited

Loading

✨ Add the `strikethrough` extension and `myst_gfm_only` configuration

✨ Add `myst_title_to_header` configuration

Upgraded to `sphinx` v4 ⬆️

Added `myst_heading_slug_func` option 👌

Upgrade to `markdown-it-py` v1.0 ⬆️

`{}` Attributes syntax

✨ Add the `strikethrough` extension and `myst_gfm_only` configuration

✨ Add `myst_title_to_header` configuration

Upgraded to `sphinx` v4 ⬆️

Added `myst_heading_slug_func` option 👌

Upgrade to `markdown-it-py` v1.0 ⬆️

`v8.2.3`: Sphinx 8.2.3

`v8.2.2`: Sphinx 8.2.2

`v8.2.1`: Sphinx 8.2.1

`v8.2.0`: Sphinx 8.2.0