Tidy up docstrings and generate parameter lists

[benradf]

It's a bit unusual to have function or rule docstrings start with a heading like that.
rules_nixpkgs generates such headings by placing them into the module docstring, e.g. here. Could the same work here, too?

Relatedly, rules_nixpkgs uses templates that also generate parameter lists and the like, e.g. here. That would be a nice improvement over the current README of rules_sh.

That said, I'm happy to leave these for a follow-up PR and already merge this one as is. After all this one achieves the goal of generating the current README from Startdoc.

Originally posted by @aherrmann in #32 (comment)