search

bandframework / Taweret

Python package for Bayesian Model Mixing
https://bandframework.github.io/Taweret/
MIT License
8 stars 8 forks source link

Clean sphinx documentation #91

Closed jared321 closed 3 months ago

jared321 commented 6 months ago

When I try to build the sphinx documentation in HTML using tox -e html, I get many warnings and two errors.

Determine if these are due to a poor tox specification or genuine. Some tools contain a flag that treats warnings as errors. It might be good to setup all documentation GH actions with such a flag when possible to ensure that documentation quality does not drift over time. This implies that we first need to get rid of all warnings and errors.

I see that the notebooks are excluded from the sphinx build. It sounds like these notebooks are examples that might be pulled out of the sphinx-based documentation. In such a case, it would be good to pull that folder out of docs.

As part of this, the docs action could be rewritten to use tox -e html.

asemposki commented 6 months ago

I have finished cleaning up my portion of the files in terms of flake8 compatibility. These include all files related to the building and testing of the Bivariate Linear class (previously written and maintained by Dan Liyanage), and my own Gaussian multivariate method and testing suite. I have also cleaned up the likelihood_wrappers.py, wrappers.py, and init.py files that showed flake8 errors. The only ones left to clean are related to the Trees class, which I'll leave for John since that is his expertise.

asemposki commented 6 months ago

I have assigned John so he will see these comments.

jared321 commented 4 months ago

The initial changes are in the main branch and the sphinx docs were automatically published to RTD from that branch to

https://taweretdocs.readthedocs.io

Everything looks reasonably good there in terms of a spot check. In particular, the PDF is available from the fly-away at the bottom left.

The work done on 91_SphinxClean was largely to get the sphinx docs switched to publishing via RTD rather than GH pages and to help integrate quality control of docs in GH actions and in PR reviews. In particular, since the RTD config was not in main I was not able to finalize the publishing of the docs to RTD officially. I will do that final work on the new branch 91_RtdPublish with some direct testing on main.

jared321 commented 3 months ago

The majority of the work needed has been done. However, I keep this Issue open until we are building the Jupyter book correctly on main as part of the release and have converged on a final set of GH actions that are compatible with out git workflow.

jared321 commented 3 months ago

All charges are now in main. Closed.