Use the shorthand notation when applicable #9339
Conversation
There was a problem hiding this comment.
@greg0ire thanks for taking care of this. I'm sorry for the amount of review comments (35!) but I wanted to mark all the places where we can get rid of ::.
By the way, I'm not sure I like replacing .. code-block:: php by :: when there's no previous line of text. The problem with :: is that it looks strange and it's not easy to understand, whereas .. code-block:: php is beautiful and self-explanatory. Ping @xabbuh what do you think?
| A lock can be used, for example, to allow only one instance of a command to run. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Can we move this to the end of the previous line? Thanks!
There was a problem hiding this comment.
While reading this comment there is at least one important difference to point out that we did not discuss on Slack: The colon of the short-hand notation will be rendered in the final document. So we need to check too if that really makes sense with each example.
| register. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Let's move this to the end of the previous line.
components/process.rst
Outdated
| :method:`Symfony\\Component\\Process\\Process::getPid` method. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with the previous line, please.
components/templating.rst
Outdated
| method is used. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
components/translation.rst
Outdated
| The constructor of the ``Translator`` class needs one argument: The locale. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
There was a problem hiding this comment.
This one will look a bit weird I think
| in order to put it to use. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
security/impersonating_user.rst
Outdated
| The listener implementation assumes your ``User`` entity has a ``getLocale()`` method. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
security/remember_me.rst
Outdated
| ``IS_AUTHENTICATED_FULLY`` role. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
security/voters.rst
Outdated
| which makes creating a voter even easier. | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
session/locale_sticky_session.rst
Outdated
| event: | ||
|
|
||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
Merge with previous line, please.
It's part of the standard
| The constructor of the ``Translator`` class needs one argument: The locale. | ||
|
|
||
| .. code-block:: php | ||
| The constructor of the ``Translator`` class needs one argument: The locale:: |
There was a problem hiding this comment.
@javiereguiluz @xabbuh that one will look a bit weird, won't it?
There was a problem hiding this comment.
I would stick with the explicit code block here
There was a problem hiding this comment.
The problem with :: is that it looks strange and it's not easy to understand, whereas .. code-block:: php is beautiful and self-explanatory. Ping @xabbuh what do you think?
I would stick with the explicit code block here
I'll extrapolate and take this as an agreement with @javiereguiluz 's feelings about :: at the beginning of a line.
There was a problem hiding this comment.
But that probably means I should amend the standard.
|
@greg0ire please, tell me when you consider this ready for merge. Thanks! |
|
I believe it's ready, but warning, I amended the standard |
| code block (read `the Sphinx documentation`_ to see when you should use the | ||
| shorthand); | ||
| code block unless it results in the marker being on its own line (read | ||
| `the Sphinx documentation`_ to see when you should use the shorthand); |
There was a problem hiding this comment.
@javiereguiluz here is the part I amended, please tell me what you think
|
Let's merge this PR too ... and let's wish there are not too many conflicts. Thanks for working on this @greg0ire. |
|
This has been merged up to |
| </container> | ||
| .. code-block:: php | ||
| :: |
There was a problem hiding this comment.
This change is wrong as this is part of a configuration-block block. Reverted in #9368.
There was a problem hiding this comment.
Woops, sorry for this!
It's part of the standard