Some API entries are empty

[SchmJo]

These API entries are empty:

• foxes.input.farm_layout
• foxes.variables
• foxes.constants

Maybe because these are variables/functions, not classes?

[isdanni]

Following, most functions in the API - Foxes Documentation page are empty. Any plans to update this?

If adding specific introduction is too much a workload you may consider copying doc strings of each class such as class FarmController(FarmDataModel): ... to the API documentation. For each package(e.g. core), there should also include a few sentences on its high-level functionalities. For documentation at least input and return parameters should be included in the docs.

linking openjournals/joss-reviews#5464 for tracking review progress.

[SchmJo]

Thanks for the remark (I was sick for two weeks, hence the late reply - sorry).

The documentation is generated by sphinx using autosummary with custom templates. This works fine for all classes (i.e., most of the foxes content), for example FarmController, but not for functions for some reason. It's a known issue which I still need to fix (any ideas, maybe?).

All classes docu is fine, reflecting the foxes sub-package structure in the API. Is my fixing this bug required for the publication? It's tedious..

Thanks again!

[isdanni]

Thanks for your update! Hope you have fully recovered.

A complete documentation(both class-level and function-level) are generally required for the publication. I'm not very familiar with using sphinx together with readthedocs but based on your description have you tried checking project module path(E.G. ./ or /../..) or raw logs for possible failed importing packages? Class modules imports working fine while function docstrings not showing up usually implies there might be some problem with customized templates.

If this is caused by sphinx package itself you may try raising an issue under the sphinx-doc repo.

Some references:

• https://stackoverflow.com/questions/64975729/modules-appearing-but-not-displaying-functions-on-readthedocs-with-no-apparent
• https://stackoverflow.com/questions/63409007/sphinx-does-not-read-my-function-docstring
• By default, make Autosummary templates generate documentation pages for classes, functions, exceptions etc sphinx-doc/sphinx#7912

[SchmJo]

Great, thanks for the links! I will try to fix this issue with these hints.

[SchmJo]

Fixed in new version v0.3.5 (now main, merged into paper). Now the docu has a completely new look, and the API entries are complete.

[SchmJo]

I will close this issue now, since the problem described here is solved. @isdanni feel free to re-open if you have doubts, thanks