HTML Rendered Documentation via Sphinx

[elbeejay]

PR to create HTML documentation using Sphinx and with an associated GitHub Actions workflow to generate and push the documentation to GitHub Pages. I think this PR covers the basics and includes most of the existing information / examples / doc-strings, but there is always room for further improvement...

What this PR does

This PR creates HTML documentation for the package by leveraging Sphinx to convert reStructuredText files into HTML, and to auto-document the .py files. Via a GitHub Actions workflow (also part of this PR), the documentation will be automatically generated and made available via GitHub Pages.

Specifically the documentation created will contain:

• Package Overview - slim two sentence intro, could use more text or larger section by itself... (or maybe find way to include readme.md file in the rendered sphinx docs)
• Installation Instructions
• Simple examples - copied from readme
• Rendered jupyter notebook examples - see notes below with details
• License information - points to license and disclaimer files
• Contributing guidelines
• API documentation

How to build and view the documentation locally

1. Install the required dependencies for both the package and documentation (see the requirements-dev.txt file associated with this PR) with the command pip install -r requirements-dev.txt
2. Navigate to the "docs" subdirectory of the repository in the command line
3. Run the makefile command make docs which builds the HTML documentation and places it locally within the "docs/build" subdirectory of the repository
4. View locally build documentation by opening the file docs/build/html/index.html in a web browser

Enabling the GitHub Pages

I think a switch will have to be flipped after merging this PR to "enable" the GitHub Pages websites. I think the settings will be within "Settings -> Pages" where Source = "Deploy from a branch" and the branch is "gh-pages" and the folder is "/(root)"

Notes on rendered Jupyter Notebooks

Rendering the jupyter notebooks as part of the documentation build comes with some benefits and limitations:

• Ensures the notebooks actually work every time the documentation is built; this is nice because then we can have confidence that they work, but comes at the drawback of making all the API calls (which takes time)
• Requires all dependencies to run the notebooks to be available to the CI machine; this is a problem for the NWIS demo as it isn't obvious to me how we'd install the basemaps plotting package without a full geospatial installation. That part of the notebook is commented out for now (so it is visible but not executed)
• Requires the notebook outputs to be cleared before commiting them to the repository; they get full run/built in the documentation so users will be able to see "complete" versions of them

[elbeejay]

@thodson-usgs and @sblack-usu this should create a good starting point for further documentation. Will ping you both as (potential) reviewers of the PR - let me know if you have any questions about the Sphinx set-up or anything.

[thodson-usgs]

Great work, Jay! I looked this over, and I think it makes sense to get an initial page up rather than wait until the doc is more complete.