Markdown or ReST syntax?

[seisman]

Sphinx supports both Markdown and ReST syntax when writing documentation. ReST syntax is more powerful but Markdown syntax is more popular and easier to write and understand.

I think Markdown syntax should be enough for this project and using Markdown syntax may lower the barrier for new contributors.

Thoughts?

[anbj]

I generally agree, but I don't think we should accommodate more for one-time contributors (read: only willing to make easy markdown changes), instead of accommodating for more-than-once contributors (read: people taking the time to master the more powerful rst syntax).

[leouieda]

@anbj unless we accommodate the one time contributors they'll never become more than once contributors.

But we can have it both ways with Myst Markdown. There's a sphinx plugin and it's a markdown variant that's just as powerful as RST but with simpler syntax.

[Esteban82]

I have the idea (I don't know if it's a good one) that when we give a workshop, we can ask the students to add an example here (or to pygmt) for approval. So, considering this, I think we should use the simplest language (markdown).

[seisman]

I think we should go with Myst Markdown. Here are some related links:

• https://mystmd.org/
• https://myst-parser.readthedocs.io/en/latest/syntax/typography.html

[Esteban82]

Fine by me.

[Esteban82]

I think we should go with Myst Markdown. Here are some related links:

• https://mystmd.org/
• https://myst-parser.readthedocs.io/en/latest/syntax/typography.html

Looks nice. How can it be implemented? Could you do it?

[Esteban82]

I think we should go with Myst Markdown. Here are some related links:

• https://mystmd.org/
• https://myst-parser.readthedocs.io/en/latest/syntax/typography.html

Looks nice. How can it be implemented? Could you do it?

@seisman should I update this paragraph (in docs/contributing.rst) with the above links?

The documentation are written primarily in reStructuredText <https://docutils.sourceforge.io/rst.html> and built by Sphinx <http://www.sphinx-doc.org/>. Please refer to :gmt-module:reStructuredText cheatsheet <devdocs/rst-cheatsheet.html> if you are new to reStructuredText.

[seisman]

I believe this section https://github.com/GenericMappingTools/gmt-examples/blob/main/docs/contributing.rst#contributing-new-examples needs a full rewrite.