JOSS review - documentation

[AndreWeiner]

Hi @gerlero,
your documentation currently misses a few items to conform with the JOSS publication guidelines. Here are a couple of items to check:

1. The README should include a short statement of need, similar to what you wrote in the article.
2. Example usage: you included a couple of code snippets that demonstrate small parts of the API, which is great; however, it would be more useful to include at least one example of a more realistic use case (not necessarily in the README); the one-liners/minimal code snippets, you could also include in the API's docstrings (see here).
3. the API has extensive type hinting, which is great; at least for the main classes (FoamCaseBase, FoamCase, Async*, FoamFile*) I suggest adding also some more elaborate docstrings describing the main purpose of the class, what it adds to a base class, what the current limitations are, and how to use it.
4. You set up automated testing; for developers/contributors, a small set of instructions on running unit tests locally would be helpful.
5. Currently, contributor guidelines are missing (refer to community guidelines in this list)

@akashdhruv, @Failxxx, @paugier

Best, Andre

[Failxxx]

Hello,
I agree with you on all the items. These correspond to the "Documentation" section of the review guidelines.

[Failxxx]

Related to: openjournals/joss-reviews/issues/7633

[gerlero]

@AndreWeiner @Failxxx Proposed changes:

1. The README should include a short statement of need, similar to what you wrote in the article.

• README: add statement of need. (Revise README.md #325)

2. Example usage: you included a couple of code snippets that demonstrate small parts of the API, which is great; however, it would be more useful to include at least one example of a more realistic use case (not necessarily in the README); the one-liners/minimal code snippets, you could also include in the API's docstrings (see here).

• README: add a realistic, self-contained, use case example. (Revise README.md #325)
• DOCS: add code snippets from README to the relevant docstrings. (Revise documentation #326)

3. the API has extensive type hinting, which is great; at least for the main classes (FoamCaseBase, FoamCase, Async*, FoamFile*) I suggest adding also some more elaborate docstrings describing the main purpose of the class, what it adds to a base class, what the current limitations are, and how to use it.

• DOCS: add more elaborate docstrings for main user-facing classes. (Revise documentation #326)

4. You set up automated testing; for developers/contributors, a small set of instructions on running unit tests locally would be helpful.
5. Currently, contributor guidelines are missing (refer to community guidelines in this list)

• README/REPO: add clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support (Revise README.md #325)
• README/REPO: in contributing section, mention how to run the tests locally. (Revise README.md #325)

[Failxxx]

Hello @gerlero,
It looks good to me.

Can you please link the PR to this issue once your changes are ready?

Sincerely,
Félix.

[gerlero]

Can you please link the PR to this issue once your changes are ready?

Of course. I’ll link the relevant PRs as I get to work on them.

[paugier]

I agree that some work is needed for the documentation. The "Documentation" section of the review guidelines is indeed a good start. Some text of the article could also be used.

Also PyFoam is mentioned but I think other Python packages related to OpenFOAM should also be mentioned in the section Statement of Need, like fluidfoam and fluidsimfoam.

[gerlero]

@paugier Proposed changes:

I agree that some work is needed for the documentation. The "Documentation" section of the review guidelines is indeed a good start. Some text of the article could also be used.

• DOCS: improve documentation following the Documentation section of the review guidelines (consider extracting text from the paper). (Revise documentation #326)

Also PyFoam is mentioned but I think other Python packages related to OpenFOAM should also be mentioned in the section Statement of Need, like fluidfoam and fluidsimfoam.

• PAPER: mention other OpenFOAM-related Python packages in the statement of need, including fluidfoam and fluidsimfoam. (Revise article #324)