sphinx-doc / sphinx-doc/sphinx

[docs] clarify the usage of `versionadded` & co

Open
#12,412 9 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

awaiting:review type:docs
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 the versionadded/versionchanged directive. 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

image

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.