Missing examples and documentation

[ziotom78]

The only documentation for the library seems to be in tests. Ideally, one would expect a short example to be included in the README. A nice example is the following package, which has been positively reviewed by JOSS referees:

https://github.com/GeoStat-Framework/pentapy

[ziotom78]

Another missing point is some API documentation. This should include a list of functions, grouped by category, a list of arguments, the return value, and a description of their purpose.

Today, Python packages are usually documented using Sphinx, and the documentation is hosted either on ReadTheDocs or GitHub pages. You can refer to pentapy again:

https://geostat-framework.readthedocs.io/projects/pentapy/en/latest/

[ziotom78]

This refers to JOSS' review («Functionality documentation», openjournals/joss-reviews#1809).

[SuperKam91]

Thank you again @ziotom78 for your advice. I have taken your comments on board and created a read the docs site for gns: https://geometric-nested-sampling.readthedocs.io/en/latest/.

It's a little rough round the edges, but hopefully it will suffice for now and I will refine it over time as I learn how to use sphinx better. Note the main sub-modules which would be used by the end user, i.e. nested_run.py, plotting.py, output.py and theoretical_funcs.py have been documented the most.

I have included a minimum working example in both the README and the read the docs pages.

[ziotom78]

Excellent! However, the documentation refers to file PACKAGEAPI.md for the full documentation of the API, yet this file does not exist in the repository. Did you forget to add it to the commit?

[SuperKam91]

@ziotom78 good spot. I have rectified this typo, the API documentation should now be live: https://geometric-nested-sampling.readthedocs.io/en/latest/index.html. As I said above, may need tidying up in a few places but hopefully will be sufficient in its current form.