Repository: wagtail/wagtail

Issue:
Documentation dependency - Upgrade Myst Parser
Our current documentation uses myst-parser version 0.18 

https://github.com/wagtail/wagtail/blob/f71ecd9a753d3fd6d824e06bd58e2c20e2d5dcf6/setup.py#L78


### Describe the solution you'd like

The latest version of this library comes with some improvements and it would be good to update. 

https://myst-parser.readthedocs.io/en/latest/develop/_changelog.html#id1


### Additional context

We need to make sure the dropping of support for Sphinx 5 will not cause issues. Along with a review of any other dependency changes that may not be compatible with Read the Docs. 

See a related issue for Documentation dependencies. https://github.com/wagtail/wagtail/issues/10426



Discussion:
These are all the deprecated support and incompatible [changes](https://www.sphinx-doc.org/en/master/changes.html) in sphinx v6: 

## Release 6.2.0 (released Apr 23, 2023)[](https://www.sphinx-doc.org/en/master/changes.html#release-6-2-0-released-apr-23-2023 "Link to this heading")

### Incompatible changes[](https://www.sphinx-doc.org/en/master/changes.html#id125 "Link to this heading")

- LaTeX: removal of some internal TeX `\dimen` registers (not previously publicly documented) as per 5.1.0 code comments in `sphinx.sty`: `\sphinxverbatimsep`, `\sphinxverbatimborder`, `\sphinxshadowsep`, `\sphinxshadowsize`, and `\sphinxshadowrule`. (refs: [#11105](https://github.com/sphinx-doc/sphinx/issues/11105))
    
- Remove `.egg` support from pycode `ModuleAnalyser`; Python eggs are a now-obsolete binary distribution format
    
- [#11089](https://github.com/sphinx-doc/sphinx/issues/11089): Remove deprecated code in `sphinx.builders.linkcheck`. Patch by Daniel Eades
    
- Remove internal-only `sphinx.locale.setlocale`

### Deprecated[](https://www.sphinx-doc.org/en/master/changes.html#id128 "Link to this heading")

- [#11247](https://github.com/sphinx-doc/sphinx/issues/11247): Deprecate the legacy `intersphinx_mapping` format
    
- `sphinx.util.osutil.cd` is deprecated in favour of `contextlib.chdir`.


## Release 6.1.0 (released Jan 05, 2023)



### Incompatible changes
- [#10979](https://github.com/sphinx-doc/sphinx/issues/10979): gettext: Removed support for pluralisation in `get_translation`. This was unused and complicated other changes to `sphinx.locale`.
### Deprecated[](https://www.sphinx-doc.org/en/master/changes.html#id169 "Link to this heading")

- `sphinx.util` functions:
    
    > - Renamed `sphinx.util.typing.stringify()` to `sphinx.util.typing.stringify_annotation()`
    >     
    > - Moved `sphinx.util.xmlname_checker()` to `sphinx.builders.epub3._XML_NAME_PATTERN`
    >     
    > 
    > Moved to `sphinx.util.display`:
    > 
    > - `sphinx.util.status_iterator`
    >     
    > - `sphinx.util.display_chunk`
    >     
    > - `sphinx.util.SkipProgressMessage`
    >     
    > - `sphinx.util.progress_message`
    >     
    > 
    > Moved to `sphinx.util.http_date`:
    > 
    > - `sphinx.util.epoch_to_rfc1123`
    >     
    > - `sphinx.util.rfc1123_to_epoch`
    >     
    > 
    > Moved to `sphinx.util.exceptions`:
    > 
    > - `sphinx.util.save_traceback`
    >     
    > - `sphinx.util.format_exception_cut_frames`
    

## Release 6.0.0 (released Dec 29, 2022)[](https://www.sphinx-doc.org/en/master/changes.html#release-6-0-0-released-dec-29-2022 "Link to this heading")
### Incompatible changes[](https://www.sphinx-doc.org/en/master/changes.html#id186 "Link to this heading")

- [#7405](https://github.com/sphinx-doc/sphinx/issues/7405): Removed the jQuery and underscore.js JavaScript frameworks.
    
    These frameworks are no longer be automatically injected into themes from Sphinx 6.0. If you develop a theme or extension that uses the `jQuery`, `$`, or `$u` global objects, you need to update your JavaScript to modern standards, or use the mitigation below.
    
    The first option is to use the [sphinxcontrib.jquery](https://github.com/sphinx-contrib/jquery/) extension, which has been developed by the Sphinx team and contributors. To use this, add `sphinxcontrib.jquery` to the `extensions` list in `conf.py`, or call `app.setup_extension("sphinxcontrib.jquery")` if you develop a Sphinx theme or extension.
    
    The second option is to manually ensure that the frameworks are present. To re-add jQuery and underscore.js, you will need to copy `jquery.js` and `underscore.js` from [the Sphinx repository](https://github.com/sphinx-doc/sphinx/tree/v5.3.0/sphinx/themes/basic/static) to your `static` directory, and add the following to your `layout.html`:
    
    {%- block scripts %}
        <script src="{{ pathto('_static/jquery.js', resource=True) }}"></script>
        <script src="{{ pathto('_static/underscore.js', resource=True) }}"></script>
        {{ super() }}
    {%- endblock %}
    
    Patch by Adam Turner.
    
- [#10471](https://github.com/sphinx-doc/sphinx/issues/10471), [#10565](https://github.com/sphinx-doc/sphinx/issues/10565): Removed deprecated APIs scheduled for removal in Sphinx 6.0. See [Deprecated APIs](https://www.sphinx-doc.org/en/master/extdev/deprecated.html#dev-deprecated-apis) for details. Patch by Adam Turner.
    
- [#10901](https://github.com/sphinx-doc/sphinx/issues/10901): C Domain: Remove support for parsing pre-v3 style type directives and roles. Also remove associated configuration variables `c_allow_pre_v3` and `c_warn_on_allowed_pre_v3`. Patch by Adam Turner.

### Deprecated[](https://www.sphinx-doc.org/en/master/changes.html#id209 "Link to this heading")

- [#10843](https://github.com/sphinx-doc/sphinx/issues/10843): Support for HTML 4 output. Patch by Adam Turner.
- [#10467](https://github.com/sphinx-doc/sphinx/issues/10467): Deprecated `sphinx.util.stemmer` in favour of `snowballstemmer`. Patch by Adam Turner.
- [#9856](https://github.com/sphinx-doc/sphinx/issues/9856): Deprecated `sphinx.ext.napoleon.iterators`.
Possibly breaking changes in Myst-Parser:

## 2.0.0
- ⬆️ UPGRADE: markdown-it-py to v3 (PR #gh-pr:773)

    - This is mainly a non-breaking change, fixing some edge cases in parsing

    - See: executablebooks/markdown-it-py and executablebooks/mdit-py-plugins

- ⬆️ UPGRADE: linkify-it-py to v2 (PR #gh-pr:675)

   - Also fixes some edge cases in parsing

   - See: tsutsu3/linkify-it-py

- ⬆️ UPGRADE: Add support for docutils v0.20 (PR #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 (PR #gh-pr:776)

   - No significant changes, see https://www.sphinx-doc.org/en/master/changes.html

- ⬆️ UPGRADE: Remove Python 3.7 support and add testing for Python 3.11 (PR #gh-pr:772)

## 0.19.0

> **_NOTE:_** It is advised (although not immediately necessary) to prefix all internal references with #. For example, [...] (my-reference), should be changed to [...] (#my-reference).

I feel the only significant change is the removal of support for `Python 3.7`. I think the updation of `myst-parser` from `0.18.1` to  `0.19.0` for now wouldn't adversely affect the project in any way.

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -139,6 +139,12 @@
     )
 }
 
+myst_url_schemes = {
+    "https": None,
+    "http": None,
+    "mailto": None,
+}
+
 # -- Options for HTML output ----------------------------------------------
 
 # Theme options are theme-specific and customise the look and feel of a theme
diff --git a/setup.py b/setup.py
--- a/setup.py
+++ b/setup.py
@@ -75,7 +75,7 @@
     "Sphinx>=1.5.2",
     "sphinx-autobuild>=0.6.0",
     "sphinx-wagtail-theme==6.1.1",
-    "myst_parser==0.18.1",
+    "myst_parser==2.0.0",
     "sphinx_copybutton>=0.5,<1.0",
 ]
 


Test patch:
diff --git a/docs/advanced_topics/testing.md b/docs/advanced_topics/testing.md
--- a/docs/advanced_topics/testing.md
+++ b/docs/advanced_topics/testing.md
@@ -287,7 +287,7 @@ class MyPageTest(WagtailPageTestCase):
 
 ### Using `dumpdata`
 
-Creating [fixtures](django:howto/initial-data) for tests is best done by creating content in a development
+Creating [fixtures](inv:django#howto/initial-data) for tests is best done by creating content in a development
 environment, and using Django's [dumpdata](https://docs.djangoproject.com/en/stable/ref/django-admin/#django-admin-dumpdata) command.
 
 Note that by default `dumpdata` will represent `content_type` by the primary key; this may cause consistency issues when adding / removing models, as content types are populated separately from fixtures. To prevent this, use the `--natural-foreign` switch, which represents content types by `["app", "model"]` instead.