search

nci / scores

Metrics for the verification, evaluation and optimisation of forecasts, predictions or models.
https://scores.readthedocs.io/
Apache License 2.0
56 stars 15 forks source link

(under development) Draft docstring template #690

Open tennlee opened 2 weeks ago

tennlee commented 2 weeks ago

The spec may not be formatted properly and may not be in the right place.

Here is a draft spec that we could improve and consider including.

tennlee commented 2 weeks ago

@nicholasloveday @rob-taggart @Steph-Chong @durgals please all feel free to comment on this one. If you can focus on the content of the spec, I'll worry about where to file it and link it in later.

tennlee commented 2 weeks ago

Partly motivated by #619

Steph-Chong commented 2 weeks ago

Sometimes people like to add a "Notes" section. I think "Notes" has to be in the right place (so to speak) to not break the readthedocs rendering. So it might be worth mentioning where to add an optional "Notes" section if it is wanted.

Steph-Chong commented 2 weeks ago

I would also add a comment about backtick rendering in API docstrings - specifically you need to use two backticks on either side of the enclosed text (with a note that this only applies to API docstrings). I would include an example.

Steph-Chong commented 2 weeks ago

I am also going back and forth on the merits of a comment about dot point rendering in API docstrings in readthedocs. Rendering of dot points in the API docstrings in readthedocs is particularly finicky. So, from that point of view, guidance might be helpful.

However, I am not sure we actually understand all the dot point rendering rules. Our usual approach to non-rendering dot points in the API docstrings is to (a) add an empty line above the dot points, and (b) if that doesn't work, just keep trying things until it does work. So if we did include a note, I am not sure what we should actually say...

But I wanted to raise it, in case anyone has thoughts on whether this is worth specifically mentioning (and if so, what we should actually say).

Steph-Chong commented 2 weeks ago

This might be too complicated for this document - but should the spec include a comment about not indenting items underneath already indented items, and not indenting twice? (When the API docstrings are rendered in readthedocs, indenting an item underneath an already indented item, or indenting twice frequently causes it to be rendered in a large grey box).

For instance, the screenshot below shows how scores.continuous.isotonic_fit is currently rendering in readthedocs (see: https://scores.readthedocs.io/en/stable/api.html#scores.continuous.isotonic_fit):

image

However, I think this is another case where we don't actually understand all the rendering logic. Sometimes it is actually okay to indent something underneath something that is already indented, or indent twice. So while it would be nice to provide guidance, I am not sure we can easily provide guidance that would be clear to someone not already familiar with the problem.

Nonetheless I wanted to raise this issue, in case anyone has a good idea about how we could clearly (and succinctly) address this. If not, we could continue to deal with this each time it comes up.

(Note: Tennessee and I have removed most of the "unintended large grey box" rendering issues from our existing API docstrings, but there are still some remaining ones that need to be dealt with).