search

bio-guoda / preston

a biodiversity dataset tracker
MIT License
25 stars 1 forks source link

Let's improve documentation #247

Open mielliott opened 1 year ago

mielliott commented 1 year ago

I suggest that we try to improve preston's documentation in preston help and preston man. I'm forgetting how to use this thing, and it makes me feel bad for newcomers

Here's some starting points:

  1. Document support for our Apache VFS-style content addressing - gz: etc. to address (de)compressed content, tar: zip: etc. to address to files in archives, line: cut: etc. to address (ranges/sets of) lines and bytes
  2. Add some basic use-case examples in preston help and/or preston man, not just to show what commands do, but how they work together. At the very least we can point to https://github.com/bio-guoda/preston#command-line-tool etc. and hope this URL persists
  3. Make it clear which commands alter/append to the provenance graph
  4. Describe how commands read from stdin when applicable
  5. Specify that preston uses Java-style regexes
  6. Keep option naming consistent, e.g. --provenanceRoot, --provenanceAnchor should be hyphenated instead of camel case
  7. Tab completion https://picocli.info/autocomplete.html
  8. Probably some other stuff I missed

I'm not so much suggesting to immediately address all of these points, but I think we should keep them in mind going forward. I do appreciate all the work that has already been put into the help & man pages, I only noticed this stuff because I use them so much 🥇

jhpoelen commented 1 year ago

@mielliott great idea to improve the documentation of preston. I made changes related to 5. and 6. can you please review?

mielliott commented 1 year ago

I love it, I'll do some stuff too

jhpoelen commented 1 year ago

Just added first pass at tab completion configuration.

jhpoelen commented 4 months ago

@mielliott still want to improve documentation? What would you like to contribute?