search

tahiri-lab / aPhyloGeo

aPhyloGeo is a multiplatform application for the analysis of genetic and climatic conditions.
https://pypi.org/project/aphylogeo/
Other
10 stars 7 forks source link

API Documentation #58

Open mmore500 opened 2 months ago

mmore500 commented 2 months ago

Could you clarify where to find API documentation? I understand that the GitHub Wiki is the main source of documentation for the project. However, I was unable to easily locate API documentation (i.e., listings of function names with parameter names and descriptions).

It would be important to put it together and make it available if it is not currently available. Here are the JOSS criteria on the topic

API documentation

Reviewers should check that the software API is documented to a suitable level.

  • Good: All functions/methods are documented including example inputs and outputs
  • OK: Core API functionality is documented
  • Bad (not acceptable): API is undocumented

I do see that many functions have docstrings, which should be an excellent starting point in the case that API documentation does not already exist. I've heard good things about mkdocs/mkdocstrings to generate API documentaiton from docstrings, although I haven't used them myself. Alternately, if the API is very small and is not expected to change or be extended/expanded over time, it may make sense to write API documentation manually.

mmore500 commented 2 months ago

This issue is related to JOSS review https://github.com/openjournals/joss-reviews/issues/6579

TahiriNadia commented 19 hours ago

Dear @mmore500 Confirmed! We generated the API documentation using Sphinx and autodoc to pull in the existing docstrings, creating a complete and accessible reference. Let us know if you have any feedback on the setup or if additional adjustments are needed! Sincerely