docs: add myst parser #274
Conversation
|
@avelanarius Please review this PR, then merge and backport to Scylla-4.x. |
|
@avelanarius ping |
| 'scylla-3.7.2.x', | ||
| 'scylla-3.10.2.x', | ||
| 'scylla-3.11.0.x', | ||
| 'scylla-3.11.2.x', | ||
| 'scylla-4.7.2.x', | ||
| 'scylla-4.10.0.x', | ||
| 'scylla-4.11.1.x', | ||
| 'scylla-4.12.0.x', | ||
| 'scylla-4.13.0.x', | ||
| 'scylla-4.14.1.x', | ||
| 'scylla-4.15.0.x', |
There was a problem hiding this comment.
Why do we have so many of these?
I think we should keep only 2-3 for each major version (3.x and 4.x).
Also, how can we set that these will be updated automatically from the repository releases?
Today our latests are 4.17.0.0 and 3.11.5.3
There was a problem hiding this comment.
Why do we have so many of these?
scylladb_markdown_recommonmark_versions lists versions using the old recommonmark library instead of the new MystParser. You don't need to change this if you add new versions to BRANCHES in conf.py.
I think we should keep only 2-3 for each major version (3.x and 4.x).
I agree. Maintainers can choose which branches to build docs for using the BRANCHES property in conf.py.
Also, how can we set that these will be updated automatically from the repository releases?
There's an open issue for it: scylladb/sphinx-scylladb-theme#848
|
@roydahan @avelanarius This PR can be merged. If you want to limit the number of branches for which the docs should be built, it should be done in a separate PR (and I agree it would be a good idea). |
Related PR: scylladb/sphinx-scylladb-theme#803
This PR replaces Sphinx's deprecated extension recommonmark with myst-parser, as per https://sphinx-theme.scylladb.com/stable/configuration/markdown.html#recommonmark-parser.
How it works
Sphinx will build the versions listed in
scylladb_markdown_recommonmark_versionswith recommonmark, and the newer versions you create from now with Myst Parser.How to test
Check the docs build and display without errors.
Next steps
Important: I recommend you backport this pull request to the
Scylla-4.xbranch so that the new versions you create from it are myst-parser compatible.