[DOC]: Add docstring example to the contributing docs#2254
Conversation
|
What do we think about these directives? https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#describing-changes-between-versions I rather like them but don't want to introduce something that's a pain to manage. If we like them, it would be nice to show one in the example. |
RDaxini
left a comment
RDaxini
left a comment
There was a problem hiding this comment.
Nice job. I think this example will certainly help contributors in the future
| where :math:`a` is the result of the equation, :math:`b` and :math:`c` | ||
| are inputs. | ||
|
|
||
| Or a figure with a caption: |
There was a problem hiding this comment.
Is it worth adding somewhere where such figures should be stored in the pvlib directory?
There was a problem hiding this comment.
I think that is intuitive enough if you see the repo layout and that most of the time us contributors copy&paste from other places. Feel free to weight in 👀
Co-Authored-By: RDaxini <143435106+RDaxini@users.noreply.github.com>
Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com>
There was a problem hiding this comment.
Personally this is exactly what I had in mind when we were discussing this! Nice work @echedey-ls! Some suggestions from my side.
Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Co-Authored-By: Adam R. Jensen <39184289+AdamRJensen@users.noreply.github.com> Co-Authored-By: Ioannis Sifnaios <88548539+IoannisSifnaios@users.noreply.github.com>
Co-authored-by: Cliff Hansen <cwhanse@sandia.gov>
kandersolar
left a comment
kandersolar
left a comment
There was a problem hiding this comment.
This looks great to me. I bet an example like this will be a good reference not just for pvlib, but other packages too, and even people's personal code.
|
Thanks @echedey-ls and all reviewers :) |
6 participants
docs/sphinx/source/whatsnewfor all changes. Includes link to the GitHub Issue with:issue:`num`or this Pull Request with:pull:`num`. Includes contributor name and/or GitHub username (link with:ghuser:`user`).remote-data) and Milestone are assigned to the Pull Request and linked Issue.Adds a docstring example to the contributing page. Now that I came back to the conversation in #2081 I see it was a discussion between @IoannisSifnaios and @AdamRJensen , so sorry for getting into it.
I still hesitate a bit on whether this is the preferred format to include this template here, maybe just linking to well documented functions is enough.