Use the shorthand notation when applicable #9339

New issue

Jump to bottom

Closed

greg0ire wants to merge 2 commits into symfony:2.7 from greg0ire:shorthand

+80 −234

Contributor

greg0ire commented Feb 26, 2018

It's part of the standard

carsonbot added the Status: Needs Review label

javiereguiluz approved these changes

View reviewed changes

Member

javiereguiluz left a 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?

components/filesystem/lock_handler.rst Outdated

@@ @@ -24,7 +24,7 @@ Usage @@
               A lock can be used, for example, to allow only one instance of a command to run.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Can we move this to the end of the previous line? Thanks!

Member

xabbuh Feb 26, 2018

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.

components/expression_language/extending.rst Outdated

@@ @@ -70,7 +70,7 @@ which returns an array of expression functions (instances of @@
               :class:`Symfony\\Component\\ExpressionLanguage\\ExpressionFunction`) to
               register.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Let's move this to the end of the previous line.

components/process.rst Outdated

@@ @@ -312,7 +312,7 @@ Process Pid @@
               You can access the `pid`_ of a running process with the
               :method:`Symfony\\Component\\Process\\Process::getPid` method.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with the previous line, please.

components/templating.rst Outdated

@@ @@ -190,7 +190,7 @@ choose which one to use for the template, the @@
               :method:`EngineInterface::supports() <Symfony\\Component\\Templating\\EngineInterface::supports>`
               method is used.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

components/translation.rst Outdated

@@ @@ -31,7 +31,7 @@ Configuration @@
               The constructor of the ``Translator`` class needs one argument: The locale.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

Contributor Author

greg0ire Feb 26, 2018

This one will look a bit weird I think

security/custom_authentication_provider.rst Outdated

               set in the configuration. Pass this argument to your authentication provider
               in order to put it to use.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

security/impersonating_user.rst Outdated

@@ @@ -236,7 +236,7 @@ the sticky locale: @@
                   The listener implementation assumes your ``User`` entity has a ``getLocale()`` method.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

security/remember_me.rst Outdated

               In the following example, the action is only allowed if the user has the
               ``IS_AUTHENTICATED_FULLY`` role.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

security/voters.rst Outdated

@@ @@ -38,7 +38,7 @@ A custom voter needs to implement @@
               or extend :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\AbstractVoter`,
               which makes creating a voter even easier.
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

session/locale_sticky_session.rst Outdated

               To do this, you need an event listener for the ``security.interactive_login``
               event:
-              .. code-block:: php
+              ::

Member

javiereguiluz Feb 26, 2018

Merge with previous line, please.

xabbuh added this to the 2.7 milestone

greg0ire force-pushed the shorthand branch from bbdadbe to 045cda2 Compare

February 26, 2018 08:30


          Use the shorthand notation when applicable

9277d29

It's part of the standard

greg0ire force-pushed the shorthand branch from 045cda2 to 9277d29 Compare

February 26, 2018 09:35

greg0ire commented

View reviewed changes

components/translation.rst

-              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::

Contributor Author

greg0ire Feb 26, 2018

@javiereguiluz @xabbuh that one will look a bit weird, won't it?

Member

xabbuh Feb 26, 2018

I would stick with the explicit code block here

Contributor Author

greg0ire Feb 26, 2018

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.

Contributor Author

greg0ire Feb 26, 2018

But that probably means I should amend the standard.


          Add extra rule about markers on their own line

016daf1

Member

javiereguiluz commented Feb 28, 2018

@greg0ire please, tell me when you consider this ready for merge. Thanks!

Contributor Author

greg0ire commented Feb 28, 2018 •

edited

Loading

I believe it's ready, but warning, I amended the standard

greg0ire commented

View reviewed changes

contributing/documentation/standards.rst

    
                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);

Contributor Author

greg0ire Feb 28, 2018

@javiereguiluz here is the part I amended, please tell me what you think

Member

javiereguiluz Mar 1, 2018

Looks good to me!

javiereguiluz added Status: Reviewed and removed Status: Needs Review labels

Member

javiereguiluz commented Mar 1, 2018

Let's merge this PR too ... and let's wish there are not too many conflicts. Thanks for working on this @greg0ire.

javiereguiluz added a commit that referenced this pull request


          minor #9339 Use the shorthand notation when applicable (greg0ire)

dc7271a

This PR was squashed before being merged into the 2.7 branch (closes #9339).

Discussion
----------

Use the shorthand notation when applicable

It's part of the standard

Commits
-------

d8faa39 Use the shorthand notation when applicable

javiereguiluz closed this

Member

javiereguiluz commented Mar 1, 2018

This has been merged up to master branch. As said in other PR, if you want to do this for the other branches, you should do it in 2.8, wait for merge, then 3.4 and wait for merge, then 4.0 and wait for merge and finally, master and wait for merger. Thanks!

greg0ire deleted the shorthand branch

March 1, 2018 17:16

fabpot reviewed

View reviewed changes

configuration/external_parameters.rst

                       </container>
-                  .. code-block:: php
+                  ::

Member

fabpot Mar 1, 2018

This change is wrong as this is part of a configuration-block block. Reverted in #9368.

Contributor Author

greg0ire Mar 1, 2018

Woops, sorry for this!

kunicmarko20 mentioned this pull request

[Docs] some doc fixes sonata-project/SonataAdminBundle#5368

Merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Status: Reviewed