[WIP] As a workaround, convert the README to MarkDown

[felixfontein]

There are multiple PRs open that modify README.rst, we shouldn't start splitting it up / moving it around / converting it to MD / ... before these are processed.

So here's a potential interim solution: convert the RST to MarkDown automatically using pandoc.

Unfortunately pandoc doesn't handle everything, including the table of contents and notes, which we both use :-(

I'm currently working on some RST to MD conversion code (using Python docutils) anyway for Ansible changelogs, once I find some more time I'll try to get that code to convert our README.rst (right now the code only exists locally on my machine, but it already handles notes, though not yet the TOC :) ).

Temporarily fixes #1411.

[felixfontein]

(If you look at the rendered version of the MarkDown, you can search for ::: to find places where pandoc broke down.)

[felixfontein]

I've pushed my Python code to https://github.com/ansible-community/antsibull-changelog/pull/139 and used it to convert SOPS's README: https://github.com/getsops/sops/blob/4208537e6f279951abc494129516d690c2086174/README.md

Apart from the image placement in 2 Usage (https://github.com/getsops/sops/blob/4208537e6f279951abc494129516d690c2086174/README.md#usage) it seems to work pretty well - or at least I didn't spot any other problems so far.

One problem is that some internal references aren't proper references, but links to IDs that GitHub generated. These sometimes don't work anymore since docutils generates slugs slightly different. I found one, namely the reference to .sops.yaml in the updatekeys command section (https://github.com/getsops/sops/blob/4208537e6f279951abc494129516d690c2086174/README.md#271updatekeys-command). It links to #using-sops-yaml-conf-to-select-kms-pgp-for-new-files, while the correct fragment is now #212using-sopsyaml-conf-to-select-kms-pgp-and-age-for-new-files. But that's easy to fix in the RST source.

[felixfontein]

BTW, you can still see how the old README.rst rendered on GitHub here: https://web.archive.org/web/20231225064248/https://github.com/getsops/sops/ - in the end it shows a login screen, you need to scroll down there, then you can see the content and eventually the README :)

[felixfontein]

@hiddeco moving to a MarkDown now is a huge PITA for all the open PRs which modify the RST file.

And moving to a MarkDown later should be done with pandoc, since it produces more human-readable output, but it does not do things like adding a TOC - MarkDown doesn't support that. So quite some more manual work is needed - probably it's better to split up the file to multiple files, or even just have a proper docsite instead of one big documentation file.

[hiddeco]

But arguably having to install a 3rd party Python library is also a PIA for these contributors... As they would have to update the README.md with their .rst changes.

I do agree that in the end having a proper docsite is the best way to go, but this is an ever bigger chunk of work.

[felixfontein]

The idea is to not have the contributors do this, but some of us do this after every merge until the situation is resolved (I can also do it all the time if nobody else wants to bother with it). My hope is that we can resolve this very soon, depending on how quick we can shorten the review queue, so it won't be much manual work on our side :)

[flatherskevin]

Any movement on this? The README is failing to render with a message that is taking too long

[felixfontein]

Closing as the README (mostly) works again... See #1411.