Documentation housekeeping and improvement

GeoscienceAustralia / uncover-ml

Machine Learning system for Geoscience Australia uncover project

Apache License 2.0

30 stars 20 forks source link

Documentation housekeeping and improvement #56

Closed brenmous closed 4 years ago

brenmous commented 4 years ago

Docs are neglected, need a few things done:

[x] Automated deployment with CircleCI
[x] Remove the manual cubist install step (is integrated as part of setuptools install)
[ ] Simple workflow tests/demo for NCI and standalone Linux (#15) (the scripts in the pbs/ directory are out of date)
[ ] Info for installing test/dev dependencies
[x] Link from docs to NCI usage is broken (and possibly others)
[x] Explicit OS package requirements
[x] Update required NCI modules
[ ] Add information about the location and usage of the example Jupyter notebooks
[ ] configuration file parsing not in table of contents and has a TODO to add an example config file

brenmous commented 4 years ago

Docstrings should be in numpy style to allow Sphinx to generate API docs from our docstrings. Quite a few of the docstrings are already in this style, but some aren't and need to be fixed. Future docstrings should be in this style. Docstrings should be limited to 72 characters (PEP8 standard) but code can be limited to 99.

Due to migrating to a more recent version of Python, I will also be using type annotations. I recommend this be done for function signatures and if it is then types are no longer required in docstrings, but if not ensure to include types in docstrings.

brenmous commented 4 years ago

I've added some detailed docstrings to the Config class that explain each attribute - this can be used as a basis for explaining the config to users.

brenmous commented 4 years ago

3 sample config files will be provided for demonstrating workflows and configuration for the most commonly used algorithms: randomforest, XGboost and SGDApprox GP. These will also be used for testing.

brenmous commented 4 years ago

Docs are in a very good place at the moment. Currently they are up-to-date with the dev branch (this will change soon when I do a new stable release). Demonstrations of all major workflows are included as well as a list of available models.

There is some stuff undocumented that I haven't worked on, such as geowavelets and tiff2kmz. This will have to be added in future (or if features are never used they should be retired).