Skip to content

Revamped the documentation about "Contributing Docs" #4223

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Sep 16, 2014
Merged
153 changes: 103 additions & 50 deletions contributing/documentation/format.rst
Original file line number Diff line number Diff line change
@@ -1,17 +1,19 @@
Documentation Format
====================

The Symfony2 documentation uses `reStructuredText`_ as its markup language and
`Sphinx`_ for building the output (HTML, PDF, ...).
The Symfony documentation uses reStructuredText_ as its markup language and
Sphinx_ for generating the documentation in the formats read by the end users,
such as HTML and PDF.

reStructuredText
----------------

reStructuredText *"is an easy-to-read, what-you-see-is-what-you-get plaintext
markup syntax and parser system"*.
reStructuredText is a plaintext markup syntax similar to Markdown, but much
stricter with its syntax. If you are new to reStructuredText, take some time to
familiarize with this format by reading the existing `Symfony documentation`_

You can learn more about its syntax by reading existing Symfony2 `documents`_
or by reading the `reStructuredText Primer`_ on the Sphinx website.
If you want to learn more about this format, check out the `reStructuredText Primer`_
tutorial and the `reStructuredText Reference`_.

.. caution::

Expand All @@ -24,14 +26,14 @@ or by reading the `reStructuredText Primer`_ on the Sphinx website.
Sphinx
------

Sphinx is a build system that adds some nice tools to create documentation
from reStructuredText documents. As such, it adds new directives and
interpreted text roles to the standard reST `markup`_.
Sphinx is a build system that provides tools to create documentation from
reStructuredText documents. As such, it adds new directives and interpreted text
roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_.

Syntax Highlighting
~~~~~~~~~~~~~~~~~~~

All code examples uses PHP as the default highlighted language. You can change
PHP is the default syntax highlight applied to all code blocks. You can change
it with the ``code-block`` directive:

.. code-block:: rst
Expand All @@ -41,7 +43,7 @@ it with the ``code-block`` directive:
{ foo: bar, bar: { foo: bar, bar: baz } }

If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
the highlighted pseudo-language:
the name of the highlighted syntax:

.. code-block:: rst

Expand All @@ -51,16 +53,18 @@ the highlighted pseudo-language:

.. note::

A list of supported languages is available on the `Pygments website`_.
Besides all of the major programming languages, the syntax highlighter
supports all kinds of markup and configuration languages. Check out the
list of `supported languages`_ on the syntax highlighter website.

.. _docs-configuration-blocks:

Configuration Blocks
~~~~~~~~~~~~~~~~~~~~

Whenever you show a configuration, you must use the ``configuration-block``
Whenever you include a configuration sample, use the ``configuration-block``
directive to show the configuration in all supported configuration formats
(``PHP``, ``YAML``, and ``XML``)
(``PHP``, ``YAML`` and ``XML``). Example:

.. code-block:: rst

Expand Down Expand Up @@ -96,32 +100,31 @@ The previous reST snippet renders as follow:

The current list of supported formats are the following:

=============== ==============
Markup format Displayed
=============== ==============
html HTML
xml XML
php PHP
yaml YAML
jinja Twig
html+jinja Twig
html+php PHP
ini INI
php-annotations Annotations
php-standalone Standalone Use
php-symfony Framework Use
=============== ==============
=================== ======================================
Markup format Use it to display
=================== ======================================
``html`` HTML
``xml`` XML
``php`` PHP
``yaml`` YAML
``jinja`` Pure Twig markup
``html+jinja`` Twig markup blended with HTML
``html+php`` PHP code blended with HTML
``ini`` INI
``php-annotations`` PHP Annotations
=================== ======================================

Adding Links
~~~~~~~~~~~~

To add links to other pages in the documents use the following syntax:
The most common type of links are **internal links** to other documentation pages,
which use the following syntax:

.. code-block:: rst

:doc:`/path/to/page`
:doc:`/absolute/path/to/page`

Using the path and filename of the page without the extension, for example:
The page name should not include the file extension (``.rst``). For example:

.. code-block:: rst

Expand All @@ -131,14 +134,29 @@ Using the path and filename of the page without the extension, for example:

:doc:`/cookbook/configuration/environments`

The link text will be the main heading of the document linked to. You can
also specify alternative text for the link:
The title of the linked page will be automatically used as the text of the link.
If you want to modify that title, use this alternative syntax:

.. code-block:: rst

:doc:`Spooling Email </cookbook/email/spool>`

You can also add links to the API documentation:
.. note::

Although they are technically correct, avoid the use of relative internal
links such as the following, because they break the references in the
generated PDF documentation:

.. code-block:: rst

:doc:`controller`

:doc:`event_dispatcher/introduction`

:doc:`environments`

**Links to the API** follow a different syntax, where you must specify the type
of the linked resource (``namespace``, ``class`` or ``method``):

.. code-block:: rst

Expand All @@ -148,7 +166,7 @@ You can also add links to the API documentation:

:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`

and to the PHP documentation:
**Links to the PHP documentation** follow a pretty similar syntax:

.. code-block:: rst

Expand All @@ -158,20 +176,55 @@ and to the PHP documentation:

:phpfunction:`iterator_to_array`

Testing Documentation
~~~~~~~~~~~~~~~~~~~~~
New Features or Behavior Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To test documentation before a commit:
If you're documenting a brand new feature or a change that's been made in
Symfony, you should precede your description of the change with a
``.. versionadded:: 2.X`` directive and a short description:

* Install `Sphinx`_;
* Install the Sphinx extensions using git submodules: ``git submodule update --init``;
* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``;
* Run ``make html`` and view the generated HTML in the ``build`` directory.
.. code-block:: text

.. versionadded:: 2.3
The ``askHiddenResponse`` method was introduced in Symfony 2.3.

You can also ask a question and hide the response. This is particularly [...]

If you're documenting a behavior change, it may be helpful to *briefly* describe
how the behavior has changed.

.. code-block:: text

.. versionadded:: 2.3
The ``include()`` function is a new Twig feature that's available in
Symfony 2.3. Prior, the ``{% include %}`` tag was used.

Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
a new branch of the documentation is created from the ``master`` branch.
At this point, all the ``versionadded`` tags for Symfony versions that have
reached end-of-life will be removed. For example, if Symfony 2.5 were released
today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you should remove the serial comma here

tags would be removed from the new 2.5 branch.

Testing Documentation
~~~~~~~~~~~~~~~~~~~~~

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _documents: https://github.com/symfony/symfony-docs
.. _reStructuredText Primer: http://sphinx-doc.org/rest.html
.. _markup: http://sphinx-doc.org/markup/
.. _Pygments website: http://pygments.org/languages/
.. _Sphinx quick setup: http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources
When submitting a new content to the documentation repository or when changing
any existing resource, an automatic process will check if your documentation is
free of syntax errors and is ready to be reviewed.

Nevertheless, if you prefer to do this check locally on your own machine before
submitting your documentation, follow these steps:

* Install Sphinx_;
* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``;
* (Optionally) Install the bundle docs and CMF docs: ``$ bash install.sh``;
* Run ``make html`` and view the generated HTML in the ``build/`` directory.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _Sphinx: http://sphinx-doc.org/
.. _`Symfony documentation`: https://github.com/symfony/symfony-docs
.. _`reStructuredText Primer`: http://sphinx-doc.org/rest.html
.. _`reStructuredText Reference`: http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _`Sphinx Markup Constructs`: http://sphinx-doc.org/markup/
.. _`supported languages`: http://pygments.org/languages/
4 changes: 2 additions & 2 deletions contributing/documentation/license.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ Symfony2 Documentation License
==============================

The Symfony2 documentation is licensed under a Creative Commons
Attribution-Share Alike 3.0 Unported `License`_.
Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_).

**You are free:**

Expand Down Expand Up @@ -46,5 +46,5 @@ Attribution-Share Alike 3.0 Unported `License`_.

This is a human-readable summary of the `Legal Code (the full license)`_.

.. _License: http://creativecommons.org/licenses/by-sa/3.0/
.. _`CC BY-SA 3.0`: http://creativecommons.org/licenses/by-sa/3.0/
.. _Legal Code (the full license): http://creativecommons.org/licenses/by-sa/3.0/legalcode
Loading