If a README file doesn't have an extension, GitHub will parse it as Markdown. Because our README files are ReST, this results in some ugly (and not very useful) READMEs when visiting the repository on GitHub.
For example, see: https://github.com/bro/btest#readme
There are two options we could take to fix this: rename README to README.rst, or create a symlink. I tried out the symlink option here, and I think the result is much more useful: https://github.com/grigorescu/btest#readme
The affected repos are:
broctl (broctl's README just instructs users to see doc/broctl.rst. This could just be a symlink)
bromagic (this can probably be deleted?)
This is done, but there is a slight problem with the bro-plugins repository.
Github apparently does not support the toctree directive - it simply leaves the space occupied by it blank. That currently makes https://github.com/bro/bro-plugins look a bit... odd (the plugin list is simply missing).
Does anyone by any change know a simple workaround for this?
We could just remove that part of the README (one less thing we
need to maintain). Each individual plugin has its own README anyway.
Hm. We could, but I think having a list with a short explanation of what each plugin does is quite helpful. And - it should not really add a lot of maintenance overhead - it only has to be touched when adding / removing modules.
yeah would prefer to keep, make it easier to navigate.
Would it work with github to do a bullet list with relative links instead of the toctree?
(However, I'm not sure if then Sphinx would complain about the sub-directory README not being included anywhere.)
After playing around for a bit - it is basically impossible to create something here that works in sphinx and in github (the links end up broken in one of the two cases).
The current solution is to change the phrasing somewhat, so it does not look odd when the links are not present on GitHub and leave everything else as is.
Besides this, everything in this ticket is done. Closing.