Adding documentation builds

[greglucas]

Change Summary

Overview

This adds sphinx documentation that can be built for easier exploration of API functionality. Based off of the workflow for this project, with an example of what this will look like when deployed: https://swxtrec.github.io/pymsis/

Future work:

• Add a GitHub deploy token so our release mechanism via GitHub Pages can work
• Set up GitHub pages branch as an orphan that we can deploy this into

New Dependencies

sphinx, pydata-sphinx-theme

New Files

Many under the docs/ folder to start the basic structure

Updated Files

• init.py

  • Added a version number, we should edit this later to be automatically done, but at least put something in for now

• pyproject.toml

  • Added a few new dependencies and a [doc] group.

Testing

Current testing is done by just building the docs on PR and uploading the artifact that can be downloaded and inspected. It would be good to post the deployed artifact somewhere for easier viewing, which we can automate via CircleCI. But that can come in follow-up PRs if people want.

[laspsandoval]

Nice! I really like the automated documentation approach. A few things:

I think we agreed PRs should be created to merge to dev branch

We might start making .md files in the docs directory to provide folks info on how to use the repo. For example add this to describe the build process for sphinx:

1. poetry install --extras "doc"
2. cd docs/source
3. poetry run sphinx-build . _build
4. open _build/index.html

Do we want to create documentation on Github Pages and/or Confluence? Also, Matt Watwood has done this for Libera in Confluence so before we reinvent the wheel we might take a look at what was done.

[laspsandoval]

Here's an example of the markdown file for Libera, which is probably far more than we need, but may be a helpful template.

documentation-sphinx.md

[maxinelasp]

Is this for external documentation? or internal? So, is this intended to replace confluence or the github wiki, or does it operate as more of a readthedocs type thing?

[greglucas]

Is this for external documentation? or internal? So, is this intended to replace confluence or the github wiki, or does it operate as more of a readthedocs type thing?

I view this as documenting the code and a little less focused on all of the confluence stuff. I think since this is a public repo, the docs should be public as well. We can certainly push to readthedocs as well if we'd prefer that route instead of GitHub Pages, I'm indifferent.

I think we agreed PRs should be created to merge to dev branch

Good catch! dev is unfortunately behind right now, but I can rebase and point to that once the merge-back PR is in.

[tech3371]

This looks like a great content to add to style guide. Or style guild could be included in this automated doc generator.

[greglucas]

Yep, I agree, I think the style guide should either go into the docs, or vice-versa the style guide point to the docs.

[maxinelasp]

I view this as documenting the code and a little less focused on all of the confluence stuff. I think since this is a public repo, the docs should be public as well.

Sounds good to me! I'd like if we could define what kind of documentation we'd like to see (more templates, anyone?) but I think this looks good! Maybe we can require documentation as part of a PR, same as tests?