(ready for review) Draft docstring template #690
Conversation
This comment was marked as resolved.
This comment was marked as resolved.
|
Partly motivated by #619 |
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
This comment was marked as resolved.
tennlee
changed the title
tennlee
force-pushed
the
docstring_spec
branch
from
16f93a6 to
710b656
Compare
tennlee
changed the title
|
@nicholasloveday , I have gone through this in detail with @Steph-Chong . We may take another look after a bit of a break, but it's ready for you to take a look at and let us know what you think. If all seems well to you, I'm happy to merge it and then do any further work in subsequent issues, so long as it's good enough. Once it's in, we can also add a link to it in the PR checklist/template/thing. I have merged it into https://scores.readthedocs.io/en/228-documentation-testing-branch/docstring_template.html along with other changes. |
docs/docstring_spec.md
Outdated
| If there is general material like a wikipedia link, other docs site etc, add it here also | ||
| See also: | ||
| If there are closely related functions, add e.g. :py:func:`scores.continuous.rmse` with a note | ||
| Examples: |
There was a problem hiding this comment.
I think that it would be good if we can add examples in most functions.
Here is an issue that I created #692
docs/docstring_spec.md
Outdated
| >>> from scores.probability import interval_tw_crps_for_ensemble | ||
| >>> fcst = xr.DataArray(np.random.uniform(-40, 10, size=(10, 10)), dims=['time', 'ensemble']) | ||
| >>> obs = xr.DataArray(np.random.uniform(-40, 10, size=10), dims=['time']) | ||
|
|
There was a problem hiding this comment.
| >>> tail_tw_crps_for_ensemble(fcst, obs, 'ensemble', 0.5, tail='upper') |
Just adding a line for where the function is called for completeness
|
|
||
| The layout below will render properly in Read the Docs. Please adjust the example text and MathJax as required. | ||
|
|
||
| Note: backticks render differently in docstrings to elsewhere. Should you wish to include text in backticks, please use double backticks - e.g. ``scores.continuous.mean_error``. (If you only use one set of backticks, the text will instead be rendered as italics in Read the Docs). |
There was a problem hiding this comment.
With the scores.continuous.mean_error example, when writing the name of a function it is better to use ":py:func:`"
Consider updating this to suggest writing function names with ":py:func:" and non-functions that you want to render as a block (or whatever it's called) with double backtracks (e.g., reduce_dims="all"). I hope that makes sense
There was a problem hiding this comment.
I see that you use ":py:func:" further down in the example. Consider just updating this example to something like reduce_dims="all"
| ''' | ||
| A short one or two line description of what the function does. | ||
|
|
||
| Additional information (e.g. a paragraph or two) may be included here following the short description. |
There was a problem hiding this comment.
Longer lines aren't wrapping on 228. I suggest limiting the line length so that it renders correctly
|
|
||
| .. math:: | ||
| \\text{mean error} =\\frac{1}{N}\\sum_{i=1}^{N}(x_i - y_i) | ||
| \\text{where } x = \\text{the forecast, and } y = \\text{the observation} |
There was a problem hiding this comment.
This needs to be split into two sections, otherwise the second line becomes part of the first equation. I suggest just using :math:` around the x and y
tennlee
changed the title
tennlee
changed the title
Here is a draft spec that we could improve and consider including.
I have merged it into branch 228 so it can be seen at : https://scores.readthedocs.io/en/228-documentation-testing-branch/docstring_template.html