Documentation for Python Package

[theo-s]

I have tried to generate the documentation using sphinx and the existing code documentation, but some change we have made to the file structure is blocking the generation of class and function documentation. I haven't been able to resolve this, but am sure it's a fairly small lift to find out how to generate the documentation automatically.

I'll take another pass this weekend, but I think this is lower priority than some of the other tasks and should not block any release.

I'll have Sam take a look at this, but he is having computer difficulties so won't be able to immediately.

[edwardwliu]

Got it, agree this is lower priority than releasing the R package and verifying correctness of the Python package. I do think we should wait to release the Python package until we resolve documentation. If I have cycles, may take a look this afternoon as well.

[theo-s]

The Python package documentation has been updated, and now can be automatically built and deployed to readthedocs

Documentation Site

Currently readthedocs is tracking the clean_docs branch instead of master, and will not automatically rebuild the site on new pushes to this branch, but has to be manually triggered to rebuild the site. It should be pretty easy to get it set up to automatically build on new pushes.

Currently I am the only maintainer of the project on readthedocs, but if either of you want to drop your account user names here, I will add you to the project so you can edit settings etc. for the generation of the site.

In order to generate the documentation site locally, one should follow the following steps:

1. Make changes to Docstring for a class, in forestry.py for example.
2. Re install the package locally (python -m pip install .)
3. Run make html in the Python/docs folder. Then the html code for the site can be found in Python/docs/build/html. To examine the site, try opening index.html here.

The rest files that generate the site layout and all of the usage examples are in Python/docs/source, so to change components of the site, one should edit these and then re run Step 3 above. Note that none of this is required when deploying to readthedocs as the installation + running of sphinx is all done in .readthedocs.yaml. If we eventually add more dependencies for building the package, we should update the readthedocs dependencies in Python/docs/readthedocs_requirements.txt, as these are installed before installing the package to generate the readthedocs site.

[theo-s]

Let me know if I can clarify anything further