Redo documentation

[sglyon]

Our documentation is woefully out of date.

It's time for an update.

I propose we make the following changes:

• Use Documenter.jl
• Use DocStringExtensions.jl to automate a lot of our docstrings (insert function signatures, type fields, etc.)
• Lighten up the docstring syntax/structure. Right now we are kind of following python conventions, but it doesn't feel quite as natural in Julia. This happened because we were one of the first packages to have docstrings and docstring generated online docs. Since then, a community standard has emerged that mostly mimics Base julia. If you work on this and don't know what to put I suggest the following:
  • Look at Documenter.jl, DocStringExtensions.jl, and Base julia for examples of what their docstrings look like. The former two packages there should give you an idea of how to use the automation tools in DocStringExtensions.jl
  • Open an issue or PR with a proposed doctoring change and the team can give feedback/guidance on the changes.
• Split the documentation into two parts:
  1. A user guide that goes over installation and usage. This section would include some examples and tutorials
  2. An API section where we just dump all the docstring info we will be re-writing.

[jstac]

@spencerlyon2 Thanks for putting this together. It would be great to see progress.

[sbromberger]

We just converted to Documenter over in LG. Overall it's great. It requires github pages for hosting if you don't have it already. Feel free to ask questions or take a look at our scripts if you need some inspiration. The Documenter folks are also really willing to help.

[sglyon]

Thank you for the heads up. I have used Documenter in a couple packages and it worked out really well.