sphinx Add support for markdown files #9139
Conversation
This adds support to use markdown files to generate the documentation. The existing `rst` files still work and this allows to mix them with markdown files. Both formats coexist without any friction. This way, a contributor can use its favorite format. Besides, markdown syntax is considered easier to write than the rst one. This might attract new contributors to the project. This also introduces a new dependency for markdown parsing: `myst-parser`. See: https://www.sphinx-doc.org/en/master/usage/markdown.html
|
I already have some existing training material for QGIS 3D. However, it is written with the markdown syntax. With this change, it will be possible to directly add it to the existing QGIS training material. |
|
Great idea 👏! |
|
Hi @ptitjano
I read this for years, and am not really convinced, but let's take the opportunity and give it a shot.
Mind opening a PR with these changes or at least a .md file for example? What matters IMHO is to experiment the build process and the outputs, and find what is compatible and what can't be or requires some configuration. |
|
Another question that comes to mind, given the QGIS website context, is if it is possible and what specific changes are needed to have the new .md files translatable... |
|
news? |
|
The QGIS project highly values your contribution and would love to see this work merged! Unfortunately this PR has had no activity in the last 14 days and is being automatically marked as "stale". If you think this pull request should be merged, please check - that all comments by reviewers have been addressed - that there is enough information for reviewers, in particular
|
|
While we hate to see this happen, this PR has been automatically closed because it has had no activity in the last 21 days despite being marked as feedback. If this pull request should be reconsidered, please follow the guidelines in the previous comment and reopen this pull request. Or, if you have any further questions, just ask! We love to help, and if there's anything the QGIS project can do to help push this PR forward please let us know how we can assist. |
Goal:
This adds support to use markdown files to generate the
documentation. The existing
rstfiles still work and this allows tomix them with markdown files. Both formats coexist without any
friction.
This way, a contributor can use its favorite format. Besides, markdown
syntax is considered easier to write than the rst one. This might
attract new contributors to the project.
This also introduces a new dependency for markdown parsing:
myst-parser.See: https://www.sphinx-doc.org/en/master/usage/markdown.html
Related: https://github.com/qgis/QGIS-Website/pull/1255