Repository navigation
[Doc]: add sphinx versioning directives #23506
Description
Documentation Link
No response
Problem
It can be unclear which features were added when just by looking at the docs, and would be helpful if at at least major features (and whatever else folks think would be a good idea) could be flagged with a version added/changed/etc directive.
Suggested improvement
Introduce the versioning directives
Per the call (link), a first step is to create a pr with some sample directives:
Additionally sort out guidance for adding directive (to which prs) and update PR guidelines accordingly :
As a first pass, my guess is anything that gets a what's new should get a version added, anything that gets an api change should get a versionchanged, and deprecated is already added as part of the decorator
matplotlib/lib/matplotlib/_api/deprecation.py
Line 210 in 862f85d
Activity
tacaswell commented on Jul 28, 2022
Before we start adding the directive to any docstrings, we should document a policy on it and get that merged.
timhoffm commented on Jul 30, 2022
Policy proposal:
.. versionadded:: should be added to the docstring for new classes, functions, methods and parameters. The entry should be placed at the end of the description block and before the Parameters section. For parameters, it should be placed at the end of the description. For minor releases 3.x.0 the bugfix-version should be left out i.e. .. versionadded:: 3.x.
class Foo: """ This is the summary. Followed by a longer description block. Consisting of multiple lines and paragraphs. .. versionadded:: 3.5 Parameters ---------- a : int The first parameter. b: bool, default: False This was added later. .. versionadded:: 3.6 """ def set_b(b): """ Set b. .. versionadded:: 3.6 Parameters ---------- b: boolNotes
mwaskom commented on Aug 1, 2022
This would be a very welcome addition for downstream libraries.
For documentation of specific parameters, the admonition produced by versionadded directive takes up a lot of vertical space, so I wonder whether just having "Put "Added in version x" in the description is a preferable policy.
story645 commented on Aug 1, 2022
@melissawm had the (great) suggestion that this should be addressed as two concurrent PRs - one with the policy and one with some sample output. Doing so would allow for easier policy tweaking on the basis of output while still keeping them independent.
@timhoffm my thinking was:
mostly because that seemed consistent with current policy and very easy to document. I don't think your comment contradicts and is more guidance on placement, but I'm not sure.
timhoffm commented on Aug 1, 2022
I belive there is value in having this styled differently from plain text. We can tune the spacing using CSS:
e.g. adding
dl.field-list .versionadded p { margin-top: 0.1em; margin-bottom: 0.1em; } dl.field-list .versionadded { margin-top: 0.3em; }quickly tested on pandas results in
instead of
timhoffm commented on Aug 1, 2022
@story645 @melissawm I don't follow why it's important to keep two independent PRs. Policy and some first samples must be developed together and match. I would have no issue doing this simultaneously within one PR.
story645 commented on Aug 1, 2022
Cause Tom said in this thread that policy should be merged first but the discussion on the call was about creating some samples first.
tacaswell commented on Aug 1, 2022
My memory of the call was that the next action was a PR adding the policy (basically what @timhoffm wrote out in #23506 (comment)) as a starting place for the discussion, but I see the notes do not agree with my memory so I apologize for not making sure everyone was on the same page before we moved on.
I agree with Tim that doing the policy and a few examples (plus it seems some styling work) in the same PR makes good sense.
jklymak commented on Aug 1, 2022
The notes are idiosyncratic 😉. If anything in them is meant to be a formal roadmap forward for a subject, we should probably stop and write it out carefully.
But I don't think this particular issue is particularly contentious that we can't be flexible on how to proceed. In particular my understanding is that we wanted a policy before we expect everyone to add these going forward, but I don't think that precluded a few examples as well.
tacaswell commented on Aug 2, 2022
I have a concern that "some" is worse than "none" and that this may be a case were (at least going forward), we need to boil the ocean.
story645 commented on Aug 2, 2022
Which is one of the reasons Melissa suggested the split PRs & I think it's a good idea. Then the policy can go in and we can build up the examples (for example 1 PR per major doc version). It also lets us split up the work more easily.
jklymak commented on Aug 2, 2022
I thought the plan was to just do this going forward. If we have to go back and do every method we will never do this.
story645 commented on Aug 2, 2022
Yeah, my rough proposal is target 3.7 for the policy, maybe 3.6 if all the 3.6 features can get marked up quickly enough. Then over time maybe the previous releases get marked up, which is mostly tedious but not difficult if we can agree on a straightforward enough policy.
story645 commented on Oct 27, 2022
There's work to do to make sure all the 3.7 PRs get labeled and there's a question about going back (possibly a sprint task?) but I think this is done enough to close this issue.