Thanks to Shawn Walker-Salas, the Scopes documentation has been
converted from ReStructured Text to Markdown, and we now use mkdocs in
place of sphinx to build it. Shawn also fixed the documentation in
many places and improved the reference generator as well as ported the
Pygments parser plugin to Python 3.

The transition to Markdown was necessary because it opens a future
avenue towards using Markdeep (once readthedocs supports it), and the
notation is also more pleasant to work with. The choice was to
continue editing documentation in rst with mounting regret as time
passes on, or make the switch early, before we *really* start adding
to it.

I have merged all changes into the main branch, and after five
thousand additional commits to get readthedocs.io to behave, the new
documentation is now available online under:

https://scopes.readthedocs.io/

In other news, I am preparing to build Linux and Windows binaries for
Scopes 0.16 to meet the July 25 release date.

Leonard

> ---------- Forwarded message ---------
> From: Shawn Walker <binarycrusader@gmail.com>
> Date: Thu, Jul 23, 2020 at 7:11 AM
> Subject: [patch] conversion to markdown (mkdocs) format documentation
> To: <~duangle/scopes-patch@lists.sr.ht>
>
>
> Greetings,
>
> I've finally finished converting Scopes' documentation to markdown
> (mkdocs) format.  I managed to get syntax highlighting working using
> the existing scopeslexer after updating it (trivially) to Python 3.
>
> Because of the size of the changes, I've chosen to instead supply the
> "patches" via a fork of the Scopes repo on hg.sr.ht:
>
> https://hg.sr.ht/~binarycrusader/scopes-md/log
>
> You will want these changesets in this order:
>
> https://hg.sr.ht/~binarycrusader/scopes-md/rev/066781654776397011580f4eae9035dbb66cb8fc
> https://hg.sr.ht/~binarycrusader/scopes-md/rev/80bcde20373036b13b423c43e5f61516a1800684
> https://hg.sr.ht/~binarycrusader/scopes-md/rev/5388b093e2c49b5f5bac1cbd7fdec77553b5cd70
> https://hg.sr.ht/~binarycrusader/scopes-md/rev/6f7c6a0a71345e3b49fdb372531df2a61bb5818b
> https://hg.sr.ht/~binarycrusader/scopes-md/rev/7e29aedecda1b1bac0f5d4f341db694af8b0e949
>
> You should be able to create a local clone of the repository and then
> use "hg graft" or "hg transplant" to cherry-pick the changes from my
> fork to another hg repo.
>
> markdown is not nearly as well-suited to formal documentation writing
> as restructured text, but it's what all the cool people use these days
> I guess...
>
> Feedback welcome.
>
> --
> Shawn Walker-Salas