sphinx-doc / sphinx-doc/sphinx
[docs] clarify the usage of `versionadded` & co
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 8k
- Forks
- 2.6k
- PR merge metrics
- No merged PRs in 30d
Description
Describe the bug
It's interesting to see that the
::construction fails when inside theversionadded/versionchangeddirective. It might actually be an issue in Sphinx (because otherwise, the::should be smart).
Originally posted in https://github.com/python/cpython/issues/120091#issuecomment-2150319649
I'm not really sure how to make it work but if it's too much work, let's just indicate the behaviour in the documentation of .. versionadded & co directives.
How to Reproduce
Welcome to documentation!
=========================
It is now::
>>> ok
It is now2::
>>> ok
.. versionadded:: 3.14 It is
now3::
>>> ok
.. versionadded:: 3.14 It is
now4::
>>> ok
.. versionadded:: 3.14
It is now5::
>>> ok
.. versionadded:: 3.14
It is now6::
>>> ok
produces
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the reproduced reStructuredText examples and the documentation for the versionadded and versionchanged directives. Compare the six :: variants, then determine whether the expected outcome is a Sphinx behavior fix or a documentation clarification; done means the directive behavior is explicitly documented or the reported behavior is resolved.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100