[docs] clarify the usage of versionadded & co

[picnixz]

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 python/cpython#120091 (comment)

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

[chrisjsewell]

I feel you are misunderstanding of how directives are parsed:
in none of these examples are the :: in the bodies, they are all in the arguments,
you have to have a new-line for it to be the body:

.. restructuredtext-test-directive:: 3.14 It is
   now3::

   >>> ok

.. restructuredtext-test-directive:: 3.14 It is
   now4::

      >>> ok


.. restructuredtext-test-directive:: 3.14
   It is now5::

   >>> ok


.. restructuredtext-test-directive:: 3.14
   It is now6::

      >>> ok

$ rst2pseudoxml test.rst --no-transforms
<document source="test.rst">
    <system_message level="1" line="2" source="test.rst" type="INFO">
        <paragraph>
            Directive processed. Type="restructuredtext-test-directive", arguments=['3.14 It is\nnow3::'], options={}, content:
        <literal_block xml:space="preserve">
            >>> ok
    <system_message level="1" line="7" source="test.rst" type="INFO">
        <paragraph>
            Directive processed. Type="restructuredtext-test-directive", arguments=['3.14 It is\nnow4::'], options={}, content:
        <literal_block xml:space="preserve">
               >>> ok
    <system_message level="1" line="13" source="test.rst" type="INFO">
        <paragraph>
            Directive processed. Type="restructuredtext-test-directive", arguments=['3.14\nIt is now5::'], options={}, content:
        <literal_block xml:space="preserve">
            >>> ok
    <system_message level="1" line="19" source="test.rst" type="INFO">
        <paragraph>
            Directive processed. Type="restructuredtext-test-directive", arguments=['3.14\nIt is now6::'], options={}, content:
        <literal_block xml:space="preserve">
               >>> ok

[picnixz]

Ah yes! it's an argument! I totally forgot about that for those directives (I think it's the only directive that does this kind of thing). Should we then perhaps say that :: is no more smart in this case?

The thing is, there isn't a "body" actually for those directives. We explicitly say

Note that there must be no blank line between the directive head and the explanation; this is to make these blocks visually continuous in the markup.

So... should we just clarify the doc?

[picnixz]

Wait.. now I'm confused, adding a blank line before seems to work (and does what I would have expected) but it's not correct according to the docs.

[chrisjsewell]

Oh no, yeh I've just noticed, that it does not have a body

it should just work like any other admonition, but has someone decided to "get clever" with only using an argument 🤷,
which yeh I do not see the point.
Lets just give it a body and allow people to use that:

.. versionchanged:: 3.11 

   The *repr()* of zero-valued flags has changed...

[picnixz]

Yes, but with the body... it works for me locally. And the HTML is consistent so I think we already did the change but we did not mention it on the docs? We haven't touched that code since 2018 roughly.

[chrisjsewell]

ok yeh it does have a body, but that it parsed separately to the (optional) first paragraph:

sphinx/sphinx/domains/changeset.py

Line 67 in b90482f

para = nodes.paragraph(self.arguments[1], '', *inodes, translatable=False)

But yeh, if you want to use a body, I feel we should definitely be telling people to use it as the body, rather than the same line as the version

[picnixz]

So... I'm not sure what should be supported but we seem to support the 2 args + body. The second argument is directly put after the version changed, whether you put that second argument on the same line as the version or on the next line (without a blankline), e.g.:

.. versionchanged:: 3.14 SHORT_DESC

.. versionchanged:: 3.14 
   SHORT_DESC

If you want a body (i.e., something that would be visually on the next line), you can put one but it will be aligned with the "Changed in version [...]" and not indented, e.g.:

.. versionadded:: 3.14
   ok

   See::

      1 + 1

   and then

gives you

On the other hand,

.. versionadded:: 3.14
   okokok

      See::

         1 + 1

      and then

gives you

EDIT: YOU CAN EVEN INSERT A NEW LINE AND IT WOULD BE TREATED NORMALLY:

.. versionadded:: 3.14

   It is now::

   >>> 1 + 1

   and then

[picnixz]

I don't know what to recommend now. I think it's just better to say "put whatever you want as a description as a body, whether it is a short description or not" but still, we should mention the alignment of the paragraph.

[chrisjsewell]

put whatever you want as a description as a body, whether it is a short description or not

yep 👍
the allowing of the body in the argument feels an over-complication, for the minimal benefit of making things a little less terse; I never actually used it like this, as I didn't even know it was allowed