[JOSS] Documentation Suggestions

[Zeitsperre]

Context: https://github.com/openjournals/joss-reviews/issues/5916

These are a few suggestions for the documentation:

• [x] For the examples, consider using Jupyter Notebooks and nbsphinx to render them. (Addressed in #390)
  • This allows for the use of both Markdown and Python code cells within the documentation.
  • Can double as another way of testing the functionality of the library (nbsphinx_execute = True)
  • Much easier to maintain (literalinclude with :linenos: means that anytime the codebase changes, the docs need to be tweaked; not a great use of your effort).
• [ ] The user API and developer documentation could benefit immensely from call signature typing and more elaborate NumPy-docstrings (Parameters/Attributes, Returns, Notes, Examples, etc.). It isn't clear to me what those documented functions/class methods accept, when being called when reading the documentation, nor when playing around with them in my IDE. This isn't the case for some functions; it just needs to be more consistently applied.
• [x] For users, I'd like to know specifically which QC checks are being performed in the treatment process (maybe listed based on currently implemented features?). (Addressed in #390)
• [ ] The documentation could also mention (and link to) other similar projects, or projects that the outputs of the treatment process could be useful for (are outputs able to be easily exported into a specific type of data spec for a particular use-case?).
• [ ] For developers, I'd like to see more of the logic under the hood explained in the developer documentation. Perhaps there's a way to list those currently implemented?
  • The nesting of functions within modules means needing to drill 3 or 4 levels down to get to function explanations; This could be flattened a bit for readability.

[vergauwenthomas]

@Zeitsperre Thanks for this comment, this is much-appreciated advice! I will add this to my todo's.

[Zeitsperre]

Hi @vergauwenthomas

The documentation is looking much better, but the API documentation should be flattened a bit if possible, specifically here: https://vergauwenthomas.github.io/MetObs_toolkit/MetObs_documentation_full.html. Addressing this would be enough for me to check off the remaining Documentation checks in the review.

[vergauwenthomas]

Hi @Zeitsperre

I am working (#434) on the documentation to

1. Make the documentation API "flatter"
2. Restructure pages (i am trying to mimic the documentation of geopandas

For now i have added all methods-designed-for-users in the doc's. In addition, i have quite a lot of classes/functions/methods that should not be used by users. These are only relevant for developers. So i am not sure if it is good pracktiche to add them to the documentation or not. @Zeitsperre Do you prefer to add these developer-specific-functions to the documentation?

[Zeitsperre]

Hey @vergauwenthomas

If there are a handful of developer-specific functions, I wouldn't add them to the user API. They should be automatically covered by the automodule for sphinx already, so a power user would probably be able to find these functions if they're looking for them.

If you really wanted to check some boxes, I would suggest having a developer section in your API docs and placing some of these functions in there. Here's an example of how we do this in a project I maintain: https://xclim.readthedocs.io/en/stable/api.html#modules-for-xclim-developers. Feel free to take some inspiration, but there's no need to perform this if the effort is high IMO.

[vergauwenthomas]

Okay, that is clear @Zeitsperre !

Here is a snapshot of the current API documentation (in #434):

• The API doc for the users is flattened, and the methods are grouped per application-ish.
• For the API doc for the developers (i.g. all functions/methods/classes) i have tested two approaches:
  1. creating a separate tab, and autosummary all the modules of the package.
  2. referring to the Module Index, which is a (recursive) list of all modules --> classes/methods/functions. (see screenshot above).

I prefer method ii, since it is the easiest approach and all relevant info can be found for the developers. @Zeitsperre are you okay with method ii?

(Since I can only deploy one version of the documentation, i have to take screenshots of my local host)

PS. I am still working on #434 for spellcheck + adding examples in the docstrings for the most common methods. I plan to merge it tomorrow, so to resolve this issue.

[Zeitsperre]

@vergauwenthomas

That looks fantastic! Much easier for users/developers to explore the library internals!

Using the module index is perfectly fine as far as I'm concerned; An experienced developer will know where to look.

[vergauwenthomas]

Hi @vergauwenthomas

The documentation is looking much better, but the API documentation should be flattened a bit if possible, specifically here: https://vergauwenthomas.github.io/MetObs_toolkit/MetObs_documentation_full.html. Addressing this would be enough for me to check off the remaining Documentation checks in the review.

@Zeitsperre, The new (flatted + docexamples) documentation is online! I have added docstring examples for the methods of the Dataset, and plan to do the same for the other classes.

I will not close this issue, since i will address your other remarks later.