Clean sphinx documentation #91
Comments
I've temporarily set this to run on PRs to develop so that I can test it. Also, I'm not having it publish any pages for now. I'll do that once all the docs are clean.
|
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. |
|
I have assigned John so he will see these comments. |
Could still render HTML and PDF format docs locally with tox.
Daniel has already established the connection between RTD and the repo, so hopefully this will work.
RTD did run automatically in the PR as hoped. However, it failed due to three warnings that John needs to fix.
Return variable docs just needed indent.
These changes were made to address flake8 issues.
Apparently installing the python package in the root of the repo and with the tox.ini in the root implies that flake8 will automatically check all Python code in the repo including the tools folder, which is not really a part of the package. Therefore, we don't need the separate check script.
We should see the PR/Standards GH action fail.
The previous commit caused GH action to fail as expected. This should fail in a similar way.
The last commit caused GH action to fail as intended. The action seems to be effective.
As before the code standards GH action should fail.
Reset last breakage. It resulted in failure as expected. Should see failure again.
Last commit did lead to GH action failure again as expected.
|
The initial changes are in the 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 |
…to RTD. This is to confirm that the docs generation/publishing is setup so that any pushes to main trigger an automatic publishing to RTD. In particular, this is accomplished outside of GH actions and special branches. This is also a confirmation that hot fixes could be made to the docs if so desired. THESE CHANGES SHOULD BE REVERTED DIRECTLY ON MAIN.
Made additions to .rst and python docstring docs to see that they are rendered locally by tox, that they are visible in the RTD test rendering for the PR, but not published in the official, public RTD docs. They did show up as expected with tox. NOTE: I want these to make it into main so that we do see them automatically incluced in the official, public RTD docs. We can then remove them as a hotfix to test the whole workflow. Note that these were also added in to generate a merge conflict with the changes made direclty on main at commit d53cbfe so that we can test the git workflow a bit as well.
Some were running on edits to PR conversations as well as upon closing. Revert to default, which seems to be working for other PR actions. If we want actions to run upon merging, then we will make actions on special branches in accord with the git workflow to run on pushes to the branch.
|
The majority of the work needed has been done. However, I keep this Issue open until we are building the Jupyter book correctly on |
What are now the official notebooks have been moved to a different location and are successfully integrated into the Taweret jupyterbook. Therefore, we can remove those files from here. All sphinx warnings are now treated as errors for HTML build. I was able to build the HTML and PDF versions locally with tox without issue. I made some typos in index.rst and tox did fail as expected.
|
All charges are now in |
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.The text was updated successfully, but these errors were encountered: