README files misidentified by GitHub

Description

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:

binpac
bro
bro-aux
bro-plugins
bro-scripts
broccoli
broccoli-perl
broccoli-python
broccoli-ruby
broctl (broctl's README just instructs users to see doc/broctl.rst. This could just be a symlink)
broker
bromagic (this can probably be deleted?)
btest
capstats
time-machine
trace-summary

Environment

None

Activity

Show:
Johanna Amann
January 12, 2016, 8:36 AM

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?

Daniel Thayer
January 12, 2016, 8:43 AM

We could just remove that part of the README (one less thing we
need to maintain). Each individual plugin has its own README anyway.

Johanna Amann
January 13, 2016, 9:16 AM

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.

Robin Sommer
January 16, 2016, 5:49 AM

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.)

Johanna Amann
January 16, 2016, 12:30 PM

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.

Fixed

Assignee

Johanna Amann

Reporter

Vlad Grigorescu

Labels

None

External issue ID

None

Components

Fix versions

Priority

Low