Consider reverting the documentation back to reStructuredText (RST)

[thatvideoshopguy]

I noticed that the documentation was converted from reStructuredText (RST) to Markdown (MD) with this commit by @seanthegeek. I would like to discuss the reasons for this change and propose converting the documentation back to RST.

RST offers several advantages over MD in the context of large-scale documentation within Sphinx:

• More extensive Sphinx integration, as RST is the native language for Sphinx.
• Better support for complex structures like tables, definition lists, and field lists.
• Built-in support for directives and roles (there is limited support with myst-parser), which are powerful ways to add semantic markup and custom functionality.
• A larger ecosystem of extensions and plugins built specifically for RST.
• Reduce the number of dependencies, as there would be no need for myst-parser.

Please share your thoughts on the initial conversion and whether there are specific reasons for using MD over RST.

Thank you for considering this suggestion and I would be happy to get involved in this conversion, if it goes ahead.

[nhairs]

As an alternative, would it be better and/or preferred to move to a documentation tool that better supports markdown?

Reasoning:

• I suspect that MD is more commonly known that RST lowering the bar to entry for contributing to the docs.
• Whilst it's probably just theme dependent, these days I find documentation generated by sphinx somewhat painful to navigate compared to newer alternatives.

Suggestion:

If you did want to move I would suggest moving to mkdocs + mkdocs-material + mkdocstrings for generating docs and mike for managing them on GitHub Pages.

Here's a sample from one of my own projects and the mkdocs.yml that generated it (may wish to poke through /docs and /scripts as well).

Helping out:

If you decide you prefer this direction let me know - I'm happy to help.

[nhairs]

I've thrown together a branch for parsedmarc + mkdocs.

Deployed version available at: https://nhairs.github.io/parsedmarc/latest/

Let me know if you'd like me to finish this off and turn it into a PR (probably a decision for @seanthegeek)