Docs Website: Upgrade notes are in RST and render poorly

[anoadragon453]

Probably the number 1 and most notable issue we receive as feedback from the community.

The upgrade page in the docs site (source) is currently generated from UPGRADE.rst in the root of the repository.

mdbook expects markdown instead of RST, and thus the page looks a bit broken. We could convert UPGRADE.rst to a markdown file, though that would break existing links to the file (and this file is linked to quite frequently).

Possible solutions I can think of:

1. Don't import UPGRADE.rst into a mdbook page and instead simply link to the page on GitHub. This is probably the easiest solution.
2. Convert UPGRADE.rst to docs/UPGRADE.md, and leave UPGRADE.rst in place with a link to the docs website. Also quite a simple solution, although anyone who's linked to a specific header on UPGRADE.rst will have a bad time.
3. Use a mdbook preprocessor to convert RST to markdown while building the book.
   • Preprocessors can essentially modify the contents of a page during book rendering. I haven't seen one for RST -> MD yet though.

Thoughts?

[wol-win]

Would it be possible to identify and count all the references to the UPGRADE.rst? Based on the result, you could decide upon the options. If the number is not too high, probably converting the doc to an md file and update the references accordingly would be the cleanest approach.

[richvdh]

I think this is probably just a plaster we need to rip off - we should get rid of .rst sooner or later, and there's no real advantage to waiting. Initially there will be a few broken links, but in a couple of months they'll basically all be gone.

If we're lucky, most links will actually be to https://github.com/matrix-org/synapse/blob/<version>/UPGRADE.rst rather than to master or develop, so they will keep working anyway.

In short, I vote for Option 2. If we're aware of broken links, we should try to fix them.

[rubo77]

2\. anyone who's linked to a specific header on UPGRADE.rst will have a bad time.

we could add the headlines with anchors in the short UPGRADE.rst file too with links to the anchor in the new md file

[anoadragon453]

we could add the headlines with anchors in the short UPGRADE.rst file too with links to the anchor in the new md file

Not a bad idea, but given the headers in the upgrade notes are so standardised and easy to Ctrl-F for, I think it'd be quite a lot of work for not a massive gain.