Use RsT for documentation instead of DocBook

[GarkGarcia]

@rocky @mmatera and I have been discussing the possibility of using RsT for inline documentation instead of DocBook for a while. There are a couple of advantages with this.

First of all, RsT is better supported and much more flexible. I think it allows us to define our own custom markup blocks, which could be very helpful for formatting the examples in Mathics' inline documentation. Furthermore, RsT offers a greater variety for output formats, which would allow us to generate HTML and PDF documentation from the same source-files. For examples, Sphix supports HTML, LaTeX and manpages.

@rocky may have some other comments about this, but those are the reason why I believe this change benefits us.

Here's whats necessary for the change:

• Figure-out which library to use to process RsT
• Figure-out how to define custom markup blocks in such library
• Write a custom markup block for the examples in our inline documentation (one that reads the custom markup of ours with > and = and formats it properly)
• Figure out how to extract the examples from the inline documentation for automated testing (maybe we could parse the docstrings as RsT and extract the examples by walking the syntax-tree?)
• Convert the inline documentation from DocBook to RsT. This would probably involve some scripting
• Convert the manual source code from DocBook to RsT. This can probably be done with pandoc or something

[rocky]

Sphinx and pygments already provide this, so just follow that. For example, for testing see https://www.sphinx-doc.org/en/master/usage/extensions/doctest.html

For formatting to a terminal, see https://github.com/rocky/python3-trepan/blob/master/trepan/lib/format.py

This is a big undertaking. So think about coexisting with what is there and doing this incrementally.

[slel]

Or look into Markedly structured text (MyST) which combines the benefits of Markdown and reStructuredText.

[rocky]

@slel I've been thinking about this on and off and here are some thoughts.

Having used both, Markdown is easier to use and probably more widely used outside of Python. (In fact, I doubt rSt is used at all outside of Python).

In the past I have tried to use Markdown in Sphinx and the Markdown rendering was inferior to rSt, but that was using probably before Markedly, and things have probably gotten better.

More important however that we use some kind of Sphinx , and that level of abstraction at which we should be thinking about this. The difference is that Sphinx understands:

• inline document testing,
• indexing,
• searching documents,

Tables, table of contents, and footnotes, are not afterthoughts and workarounds as is the case in both rSt and markdown.

That said, whoever gets down to doing this wil probably have the final say. So if you feel strongly about it, the best way to influence this is to do the work.