Adding documentation

[adam-a-a]

While we've had some discussion about it, I think we should opt for setting up readthedocs for this project. I understand the concerns about creating more bottlenecks, but we could technically have readthedocs set up and ready to receive new documentation, even if a backlog of necessary documentation were to build up (not preferable, but worst-case scenario). At least we'd have readthedocs at the ready if we chose to move forward with it.

I vote to give it a shot, see how we fare with adding some simple .rst files, and take it from there. @lbianchi-lbl I know I poked you about this a couple weeks back. Would this be much of a lift?

To the rest of the team--thoughts?

[kurbansitterley]

Would be nice to have readthedocs for this project. We have some of the documentation in .docx format already for some of the unit models.

I am wondering what your vision for what documentation for the surrogate models would look like?

Also- this project has much fewer resources available that WaterTAP, and documentation is often low priority there. I know that I don't have bandwidth at the moment to start making rst files.

[adam-a-a]

In my view, given the growth of the team, I think we could have others contributing to .rst files. They aren't too bad once you crank out a few, and I'd be willing to help the team with learning how to implement them. As for the surrogate models, they'd get similar documentation and provide explanation for what the surrogates are based on, which would be useful.

To me, I think if @lbianchi-lbl is still able to help set us up with readthedocs, we should give it a shot. Worst case scenario- and I doubt this- but worst-case scenario is that we end up with a bare readthedocs for a while.

[kurbansitterley]

Yes if we can get a readthedocs set up, .rst files aren't too bad given we have docs for these models already. @zacharybinger have you ever written .rst?

[zacharybinger]

@kurbansitterley I haven't written any .rst files, but I have done some Markdown and LaTeX which I think are similar?

[lbianchi-lbl]

The (currently empty) ReadTheDocs site is up: https://watertap-seto.readthedocs.io/en/latest/. If y'all create a PR with all the necessary changes, I can review it and set up the ReadTheDocs PR integration.

You should be able to use the WaterTAP configuration as a reference. Off the top of my head the main files would be:

• [x] .readthedocs.yaml file
• [x] docs directory
• [x] docs/conf.py
• [ ] docs/index.rst
• [ ] docs/Makefile (optional)
• [x] Adding the Sphinx dependencies to requirements-dev.txt

[adam-a-a]

For now, I set fail_on_warning = false in my readthedocs PR #35 , just to get the readthedocs test to pass. Basically, a whole bunch of apidoc warnings pop up, and I forget how to resolve these. I want this issue to serve as a reminder to go back and fix those warnings.