Open picnixz opened 1 month ago
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
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?
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.
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...
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.
ok yeh it does have a body, but that it parsed separately to the (optional) first paragraph: https://github.com/sphinx-doc/sphinx/blob/b90482fc8147dc7d171c07897e11472fb1ed2462/sphinx/domains/changeset.py#L67
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
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
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.
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
Describe the bug
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