Migrate to docs written in Markdown

[dkastl]

I think with version 3.0 of pgRouting we could use Markdown to generate documentation. And there are quite nice tools like this one:

• https://github.com/rust-lang-nursery/mdBook
• https://github.com/datprotocol/book

[cvvergara]

Currently: The documentation examples are added like this:

:Example: Minimum Spanning Forest

.. literalinclude:: doc-pgr_kruskal.queries
   :start-after: -- q1
   :end-before: -- q2

A lot of documentation tables of inner queries are added like this:

Inner query
-------------------------------------------------------------------------------

.. rubric::edges_sql

.. include:: pgRouting-concepts.rst
   :start-after: basic_edges_sql_start
   :end-before: basic_edges_sql_end

Q1. does any of those tools allow something similar?

---

Q2. How would it affect gh-pages to keep the non 3.0 documentation?

[dkastl]

Well, I don't actually know and didn't think about this case. So to answer Q1 I had to google a bit. And I don't really understand Q2, but this ticket is not so high priority and maybe we will never do it. I just like Markdown more than Retructured Text.

[dkastl]

Just for myself as a reminder to read this later: https://docs.microsoft.com/en-us/contribute/how-to-write-use-markdown

[cvvergara]

Well, pgRouting & workshop can keep the sphinx the other repos can use other stuff

[dkastl]

Maybe solved by #34 using Docusaurus?