Commits on Nov 13, 2023

1. Get a basic README in place …

   Alright, so I don't love this, but here, aim to get a basic River README
   in place for GitHub friendliness, largely via duplication.
   
   Godoc is odd to say the least. These days it does dump a project README
   automatically into godoc if one was present, but it's always a second
   class citizen: it's collapsed when the user first visits the doc page,
   and doesn't offer some niceties like the TOC that's generated for
   `doc.go`. I searched around, and there's no easy compromise that gets
   the best of both worlds.
   
   So here:
   
   * Move old README to `docs/development.md`.
   * Make edits to `doc.go` so that it's more agnostic as to whether it's
     in godoc or rendered Markdown.
   * Streamline the old `doc.go` somewhat for length. Add list of features
     that link out to our docs.
   * Copy `doc.go` largely unedited to `docs/README.md`.
   
   The trick with `docs/README.md` is that GitHub will still find a README
   there and render it as the top level of a project, but godoc _won't_
   find it and dump it into godoc (so we don't accidentally duplicate the
   content twice in godoc).
   
   On the way from `doc.go` to `docs/README.md` I made a couple small
   tweaks for GitHub friendliness:
   
   * Gave it an h1 of "River".
   * Added badges.
   * Starts with "River is a" instead of "Package River is a".
   * Dedented all the headings. One thing that sucks about godoc is it
     won't render anything except an h1-level heading, but these look way
     too screamy in most Markdown renderings.
   * Made all the code blocks Go-formatted. Godoc won't respect the three
     backtick syntax for codeblocks, so we can't use that there, but we
     also can't specify a language _without_ using them for GitHub.
   
   Obviously, this isn't a great situation. I tried the use of the goreadme
   tool in #19, but that comes with significant problems that aren't
   fixable without issuing them pull requests.
   
   For now, I propose that we duplicate changes manually between the two
   documents while making them, and eventually write our own tool to do the
   duplication. This is easier than it sounds because we can leverage Go's
   internal tool for parsing godoc.

   

   brandur committed Nov 13, 2023
   Configuration menu

   • View commit details
   • Copy full SHA for 60f0db2
   • Browse repository at this point

   Copy the full SHA

   60f0db2 View commit details

   Browse the repository at this point in the history