Update documentation

Update the installation and usage documentation to reflect changes made in recent merges, notably the refactoring of the datamodules and the addition of saliency maps.

added 2 commits

• 557d095c - [doc] Add documentation about train-analysis
• e8829c10 - [doc] Fix typos

Compare with previous version

I'm having trouble understanding what these docstrings mean:

https://gitlab.idiap.ch/biosignal/software/mednet/-/blob/update-doc/src/mednet/models/transforms.py?ref_type=heads#L31

https://gitlab.idiap.ch/biosignal/software/mednet/-/blob/update-doc/src/mednet/models/transforms.py?ref_type=heads#L79

Also this file contains some duplicated docstrings that probably need to be rewritten.

added Documentation Requires benchmarking labels

The _process_sample function is in a weird state, with a lot of code commented out. We should decide what it returns and update the docstring accordingly.

https://gitlab.idiap.ch/biosignal/software/mednet/-/blob/update-doc/src/mednet/engine/saliency/interpretability.py?ref_type=heads#L330

There's obviously a typo here but I can't figure out what a dunder len method is supposed to be.

https://gitlab.idiap.ch/biosignal/software/mednet/-/blob/main/src/mednet/data/typing.py?ref_type=heads#L78

added 1 commit

• e079a222 - [doc] Fix typos

Compare with previous version

added 1 commit

• 024d4dee - [doc] Clarifications in transforms docstrings

Compare with previous version

added 1 commit

• d4fee13b - [doc] More changes on transforms docstrings

Compare with previous version

added 1 commit

• 3f49fa58 - [doc] Update api.rst

Compare with previous version

There are a lot of inconsistencies in how the docstrings are formatted. This does not impact the generated documentation but we should probably follow some guidelines. I'm listing here what I noticed for reference and discussion. Some of it is definitely nitpicky on my part.

1. We seem to be using numpy-style docstrings with pep484 (typhints) annotations. The sphinx documentation show an example of how they should be formatted: https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy (function_with_pep484_type_annotations)

Notable points are:

• A single empty line between function description, parameters, and returns
• No spaces between the different parameters
• All sentences start with a capital letter and end with a dot
• Returns contains the type of the return value, as well as a description.

2. Verbs are sometimes written in infinitive and other times in present tense. e.g. compute ... vs. computes .... We should decide which to use.

3. We should use types we defined in our data model. Write DataModule instead of data module or datamodule.

4. Package names are sometimes capitalized, sometimes not: Lightning vs. lightning. I'd say we should always lower-case them.

5. Functions expecting a path to something can be ambiguous. We should write "path to ..." and "directory in which ..." to make clear if we want a file or a directory.

6. File types are sometimes written as PDF or pdf or .pdf. I'd personally choose .extension.

7. (extremely nitpicky) Words with multiple spellings can be both found: normalize and normalise.

8. Should examples in our documentation match those in our --help commands?

Our SPDX headers show Copyright © 2023. I am not sure if that is how it should be to indicate the year it was made, or if we should update them to 2024 or 2023 - 2024.

added 3 commits

• faea7070 - [doc] Cleaned up interpretability _process_sample()
• e4a8dbea - [doc] Reformatted docstrings to proper numpy-style
• 83c01d55 - [doc] Various docstring improvements

Compare with previous version

added 22 commits

• 83c01d55...6ce6f1a6 - 5 commits from branch main
• 6ce6f1a6...917e86f3 - 7 earlier commits
• d5ef968e - [doc] Fix typos
• f35f0912 - [doc] Fix typos
• 791e4152 - [doc] Clarifications in transforms docstrings
• caeabcf6 - [doc] More changes on transforms docstrings
• 9e60e08c - [doc] Update api.rst
• 14de2dc6 - [doc] Cleaned up interpretability _process_sample()
• ec656ca4 - [doc] Reformatted docstrings to proper numpy-style
• fe2424b7 - [doc] Various docstring improvements
• 2f925c77 - [test] Fix import for typehints
• 0d7e2872 - [doc] Remove type aliases from docstrings because of autodoc issue

Compare with previous version

added 1 commit

• 3240277a - [test] Update assert

Compare with previous version

added 1 commit

• 257f53a8 - [doc] Doc fixes

Compare with previous version

@dcarron - thanks for all the commits. Are we OK to merge his one?

We still have to update the results and benchmarking parts, though I'd say we can merge and make another branch for that when we get to it.

Sounds sensible. Let me have a look at the current state tomorrow.

After discussing this with André, I'll go ahead and edit docstrings to use the same verb tense everywhere before we merge.

I'll also check whether it's possible to have tests for docstring validation.

It might also be worth writing our "docstring recommendations" formally somewhere as a reminder? The formatting is not critical but since it's a public package that can be used outside Idiap it would be nice to have something consistent. What do you think?