Add documentation

[kmdalton]

I realize the point of rs-booster is to add function without onerous requirements for testing and documentation. However, I just realized that I have

• no idea what is in rs-booster apart from what I have contributed

• no idea how to find out

  At the very least, we should have some kind of documentation listing all the command line apps with a brief description of what they do. In addition, we should have instructions for contributors.

[DHekstra]

@dennisbrookner perhaps it would be useful for you to take a first stab at this and, at the same time, familiarize yourself with what's already in the code base.

[dennisbrookner]

Yeah can do! Might happen sorta piecewise overtime, but I can start thinking about this.

[DHekstra]

That's understood!

[dennisbrookner]

This will be straightforward via the sphinxcontrib.autoprogram extension.

One quick note, to explain the changes I'll be making elsewhere: in order for this extension to do it's thing, it needs access to the argparse.ArgumentParser directly. This means that if I want to build docs via:

.. autoprogram:: rsbooster.thing:parse_arguments()
   :prog: rs.thing

then thing.py must look like this:

def parse_arguments():
    parser = argparse.ArgumentParser
    # blah blah blah
    return parser

def main():
    parser = parse_arguments()
    args = parser.parse_args()

and NOT like this:

def parse_arguments():
    parser = argparse.ArgumentParser
    # blah blah blah
    return parser.parse_args()

def main():
    args = parse_arguments()

Most/all of the current rs-booster functions work like the latter and will need to be refactored. Probably not cooincidentally, rs.mtzdump works like the former, probably because this same problem happened in the past!!

[dennisbrookner]

Just published an initial sketch of the docs branch:

https://github.com/rs-station/rs-booster/tree/docs

[dennisbrookner]

I think the docs branch is pretty much ready to go as far as having all of content in place. At this point, I'd love to call in an assist on getting all of the Read The Docs / GitHub Actions stuff set up.

[JBGreisman]

Sounds good -- if you start up a PR for this, I'll be able to have a look at some point in the future. I could put together a similar GitHub action / self-hosted setup as for rs