diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index d6c2bc06491..072794b6226 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -52,6 +52,8 @@ the highlighted pseudo-language: A list of supported languages is available on the `Pygments website`_. +.. _docs-configuration-blocks: + Configuration Blocks ~~~~~~~~~~~~~~~~~~~~ diff --git a/contributing/documentation/index.rst b/contributing/documentation/index.rst index cd25642aaab..08782431605 100644 --- a/contributing/documentation/index.rst +++ b/contributing/documentation/index.rst @@ -6,5 +6,6 @@ Contributing Documentation overview format + standards translations license diff --git a/contributing/documentation/overview.rst b/contributing/documentation/overview.rst index 1faa454a396..bedfc43dc44 100644 --- a/contributing/documentation/overview.rst +++ b/contributing/documentation/overview.rst @@ -161,55 +161,8 @@ tags would be removed from the new 2.5 branch. Standards --------- -In order to help the reader as much as possible and to create code examples that -look and feel familiar, you should follow these rules: - -* The code follows the :doc:`Symfony Coding Standards` - as well as the `Twig Coding Standards`_; -* Each line should break approximately after the first word that crosses the - 72nd character (so most lines end up being 72-78 characters); -* To avoid horizontal scrolling on code blocks, we prefer to break a line - correctly if it crosses the 85th character; -* When you fold one or more lines of code, place ``...`` in a comment at the point - of the fold. These comments are: ``// ...`` (php), ``# ...`` (yaml/bash), ``{# ... #}`` - (twig), ```` (xml/html), ``; ...`` (ini), ``...`` (text); -* When you fold a part of a line, e.g. a variable value, put ``...`` (without comment) - at the place of the fold; -* Description of the folded code: (optional) - If you fold several lines: the description of the fold can be placed after the ``...`` - If you fold only part of a line: the description can be placed before the line; -* If useful, a ``codeblock`` should begin with a comment containing the filename - of the file in the code block. Don't place a blank line after this comment, - unless the next line is also a comment; -* You should put a ``$`` in front of every bash line; -* The ``::`` shorthand is preferred over ``.. code-block:: php`` to begin a PHP - code block; -* You should use a form of *you* instead of *we*. - -An example:: - - // src/Foo/Bar.php - - // ... - class Bar - { - // ... - - public function foo($bar) - { - // set foo with a value of bar - $foo = ...; - - // ... check if $bar has the correct value - - return $foo->baz($bar, ...); - } - } - -.. caution:: - - In Yaml you should put a space after ``{`` and before ``}`` (e.g. ``{ _controller: ... }``), - but this should not be done in Twig (e.g. ``{'hello' : 'value'}``). +All documentation in the Symfony Documentation should follow +:doc:`the documentation standards `. Reporting an Issue ------------------ diff --git a/contributing/documentation/standards.rst b/contributing/documentation/standards.rst new file mode 100644 index 00000000000..52834c6f480 --- /dev/null +++ b/contributing/documentation/standards.rst @@ -0,0 +1,107 @@ +Documentation Standards +======================= + +In order to help the reader as much as possible and to create code examples that +look and feel familiar, you should follow these standards. + +Sphinx +------ + +* The following characters are choosen for different heading levels: level 1 + is ``=``, level 2 ``-``, level 3 ``~``, level 4 ``.`` and level 5 ``"``; +* Each line should break approximately after the first word that crosses the + 72nd character (so most lines end up being 72-78 characters); +* The ``::`` shorthand is *preferred* over ``.. code-block:: php`` to begin a PHP + code block (read `the Sphinx documentation`_ to see when you should use the + shorthand); +* Inline hyperlinks are **not** used. Seperate the link and their target + definition, which you add on the bottom of the page; +* You should use a form of *you* instead of *we*. + +Example +~~~~~~~ + +.. code-block:: ReST + + Example + ======= + + When you are working on the docs, you should follow the `Symfony Docs`_ + standards. + + Level 2 + ------- + + A PHP example would be:: + + echo 'Hello World'; + + Level 3 + ~~~~~~~ + + .. code-block:: php + + echo 'You cannot use the :: shortcut here'; + + .. _`Symfony Docs`: http://symfony.com/doc/current/contributing/documentation/standards.html + +Code Examples +------------- + +* The code follows the :doc:`Symfony Coding Standards` + as well as the `Twig Coding Standards`_; +* To avoid horizontal scrolling on code blocks, we prefer to break a line + correctly if it crosses the 85th character; +* When you fold one or more lines of code, place ``...`` in a comment at the point + of the fold. These comments are: ``// ...`` (php), ``# ...`` (yaml/bash), ``{# ... #}`` + (twig), ```` (xml/html), ``; ...`` (ini), ``...`` (text); +* When you fold a part of a line, e.g. a variable value, put ``...`` (without comment) + at the place of the fold; +* Description of the folded code: (optional) + If you fold several lines: the description of the fold can be placed after the ``...`` + If you fold only part of a line: the description can be placed before the line; +* If useful, a ``codeblock`` should begin with a comment containing the filename + of the file in the code block. Don't place a blank line after this comment, + unless the next line is also a comment; +* You should put a ``$`` in front of every bash line. + +Formats +~~~~~~~ + +Configuration examples should show all supported formats using +:ref:`configuration blocks `. The supported formats +(and their orders) are: + +* **Configuration** (including services and routing): Yaml, Xml, Php +* **Validation**: Yaml, Annotations, Xml, Php +* **Doctrine Mapping**: Annotations, Yaml, Xml, Php + +Example +~~~~~~~ + +.. code-block:: php + + // src/Foo/Bar.php + + // ... + class Bar + { + // ... + + public function foo($bar) + { + // set foo with a value of bar + $foo = ...; + + // ... check if $bar has the correct value + + return $foo->baz($bar, ...); + } + } + +.. caution:: + + In Yaml you should put a space after ``{`` and before ``}`` (e.g. ``{ _controller: ... }``), + but this should not be done in Twig (e.g. ``{'hello' : 'value'}``). + +.. _`the Sphinx documentation`: http://sphinx-doc.org/rest.html#source-code diff --git a/contributing/map.rst.inc b/contributing/map.rst.inc index 7f19882321a..62a5e9f2f9e 100644 --- a/contributing/map.rst.inc +++ b/contributing/map.rst.inc @@ -13,6 +13,7 @@ * :doc:`Overview ` * :doc:`Format ` + * :doc:`Documentation Standards ` * :doc:`Translations ` * :doc:`License `