jranalli / solartoolbox Goto Github PK

solartoolbox is quite generic - perhaps something like solarspatialtools would better convey the intended scope?

Below is the section about software documentation from the reviewer checklist for JOSS submissions. The only documentation is the README page.

I am hesitant to check the unchecked items. My concerns are pasted below each check box item.

Documentation

• A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?

The first paragraph of the README page should specify the scope of this package, which is tools for spatial analysis of solar-related data. This is clear from the paper.

• Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.

• Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).

Twelve "demos" are included; some are jupyter notebooks, others are python scripts. The notebooks are adequately commented. cmv_demo.ipynb does not run (won't preview on github). cmv_demo.py has minimal commenting.

It would be very helpful if the demos were rendered as documentation pages. Without any sort of introduction for new users, it is difficult to know where to enter these examples to learn how to use the tools in this package.

• Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?

I don't think so. The primary failiing is the lack of a catalog of public functions. One must browse each code modules to discover what's available. Each function appears to be adequately documented, but checking again requires browsing each code file.

• Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?

Without the benefit of API documentation, test coverage of public functions is difficult to judge.

• Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

More could be provided on this topic. The single sentence doesn't convey a commitment by maintainers to support the package into the future.