Standardize package-level readmes

[teutoburg]

The individual readme files for each package are currently a bit inconsistent. I noticed the following:

• While most packages use .rst, some use .md.
• The location of the readme is sometimes the top-level directory of that package, and other times inside a docs folder.
• There doesn't seem to be a standard structure for the content of the readme, other than maybe METIS and MICADO.
• Several (admittedly rather empty) packages have no readme et al. at all.
• Only METIS and MICADO appear to be on readthedocs.io.

De formato

The first point raises the question of which format, RST or Markdown, should become the standard for these readmes. Some considerations:

Advantages of RST

• Of the readmes currently in existence, the majority is in this format, which means less work is needed.
• AFAIK, it's easier to use Sphinx with RST out of the box.
• Python docstrings in the actual code are basically RST as well. However, that's more of a concern in ScopeSim, IRDB doesn't contain much (documented) code anyway.

Advantages of markdown

• The file itself is more portable, not only the rendered version on readthedocs.io. It also renders automatically on GitHub itself, meaning you don't need to go out to another site. Edit: RST files also render on GitHub, but not on all devices, which is not an issue for markdown...
• It's trivial to include badges. As mentioned before, it could be a nice addition to include (some or all) of a package's badges from the badge report also in the package-level readmes, so the information is in one place (per package).
• The raw code is less verbose than RST.
• The notebooks (which are also part of the documentation) are also written in markdown.
• Could include mermaid diagrams 😃

I probably forgot a few points in both...

De loco

The top-level package directories are often pretty crowded already, so a separate docs folder seems reasonable. GitHub seems to have no issue finding a readme file in a docs subfolder. (edited)

Not sure if either location makes it any more or less straightforward for Sphinx/readthedocs.

De Sphinge (or whatever the ablative case for Sphinx would be)

As a sidenote while at it: There are some functions for dealing with Sphinx etc which might need some attention. Edit: I'm talking about docs/code, and probably also the files in docs/source/reference...

Edit:

Addendum

After looking at it again, I found some files overview_<pkg_name>.rst in docs/source. Should these be moved to the respective packages?