sphinx Add support for markdown files

[ptitjano]

Goal:

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

Related: https://github.com/qgis/QGIS-Website/pull/1255

[ptitjano]

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.

[Guts]

Great idea :clap:!

[DelazJ]

Hi @ptitjano

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.

I read this for years, and am not really convinced, but let's take the opportunity and give it a shot.

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.

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. I want to be sure of how things correctly play before requiring that the docker image for build on the server gets updated. Thanks for your understanding.

[DelazJ]

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...

[DelazJ]

news?

[github-actions[bot]]

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

• link to any issues which this pull request fixes
• add a description of workflows which this pull request fixes
• add screenshots if applicable In case you should have any uncertainty, please leave a comment and we will be happy to help you proceed with this pull request. If there is no further activity on this pull request, it will be closed in a week.

[github-actions[bot]]

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.

[Guts]

@ptitjano do you need some help to comply with @DelazJ requirements?