Consistent documentation links

[cliffckerr]

Goal: get links to work:

1. in the documentation (clicking on a link on one doc page brings you to the appropriate other doc page)
2. in the READMEs (clicking on a link on GitHub brings you to the appropriate other readme)

Currently, some docs links lead to the GitHub readmes, and some readmes which should redirect internally instead are hard-coded to https://github.com/institutefordiseasemodeling/covasim, which won't work if you're navigating the repo on your own fork.

This might be useful (or maybe not): https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#setup-external-links

Ideally, we want to use relative RST links like ../../docker/README.rst because only these will be parsed correctly by different GitHub forks. But will need to preprocess these in the Sphinx build to have the docs point to the right place. This mapping can be hard-coded in the docs since the contents of the files will change, but it should be quite rare that a new readme is added.

[JSchripsema-IDM]

This can be solved by setting docs up the way I initially did, with RST source files in the docs folder that can use Sphinx processing. We could potentially emit plain text files from the Sphinx build to serve as READMEs in the code folders, but using the READMEs as both user-readable files and source for the Sphinx build means everything has to be hard-coded because the READMEs aren't processed by Sphinx when viewed in the repo.

[ckerr-IDM]

@JSchripsema-IDM even if there isn't a way to do it automatically in sphinx (which there might be, if i'm interpreting the link above correctly), i think all we need to do is add a python preprocessing step to copy the repo rst files into the docs folder, do a regex replacing the rst links with docs ones, and then run sphinx build. i can do that but it will take me a bit of time which i won't have until at least the middle of next week. we can't have the readmes not in the right folders on github. we could have them live in the docs folder and be processed by the build process into text files in the folders, but i think it would be more user-friendly to go the other way.

we're obviously not the first people to encounter this and it seems there are various solutions, e.g.

• if we don't want to use sphinx, mkdocs works out of the box with markdown: https://mkdocs.readthedocs.io/en/0.9/user-guide/writing-your-docs/#linking-documents
• another solution using mkdocs: Support both github and sphinx links commercialhaskell/stack#1506
• there's an nbsphinx extension which claims to do it: Compatible links between GitHub and Sphinx... esp8266/Arduino#4409
• several people suggested just writing, or have written, python preprocessors

[celiot-IDM]

Folks ...

I would like to hold off making changes to the content management system until I've had a chance to review the whole story top to bottom. This is not something we need to fix for the initial release, so I would like to take the time for a thorough review.

Thanks,
Charles

[guyclarkemarshall]

Adding to these README suggestions, a minor point in the FAQs: On https://docs.idmod.org/projects/covasim/en/latest/faq.html#conceptual-questions the example relating to MultiSim has "verbose=-1" which should be "verbose=1".
This can be reproduced and solution validated by following the example on that page.