SRW App Automated Technical Documentation

[gspetro-NOAA]

Members of the SRW App code management team have expressed interest in having automated technical documentation for the SRW App. In particular, @christinaholtNOAA has requested that this functionality be added to the SRW App repository. I am summarizing the request here.

Purpose/Need: The purpose of this feature is needed to ensure that documentation is thorough, accurate, and up-to-date. Currently, the SRW App does not have a mechanism for this. As a result:

• Many SRW App files lack in-code documentation.
• Files that have in-code documentation still require the developer to go into the file and read the documentation (it is not built in human-readable form or easily accessible, like documentation in ReadTheDocs or Doxygen is).
• There is no mechanism to enforce the requirement that developers document their code, so undocumented code can be added to the repository, which poses a problem for accuracy, thoroughness, and ultimate usefulness of the repository and its documentation.

Requirements:

• Documentation must be user-friendly/human-readable.
• Documentation must be thorough (i.e., all functions, parameters, return values documented).
• Documentation standards must be enforced automatically (i.e., doc build generates errors if documentation is missing).
• Documentation of Python, YAML, and Bash scripts must reside in one location (i.e. not hosted on separate platforms and not maintained in a separate branch from the source code).

Proposed Solution: My proposed solution for automating the documentation is provided in this plan (viewable to anyone with a NOAA email; others may request view access).

[christinaholtNOAA]

@gspetro-NOAA, thank you for writing up this verbal request.