Permalink
Browse files

feature #4223 Revamped the documentation about "Contributing Docs" (j…

…aviereguiluz)

This PR was merged into the 2.3 branch.

Discussion
----------

Revamped the documentation about "Contributing Docs"

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | yes
| Applies to    | 2.3+
| Fixed tickets | -

This is the first step into completely revamping the *Contributing* section documentation. The main changes are:

  * A much more friendly and welcoming tone.
  * Thorough and step-by-step explanations that assumes no previous knowledge from the reader.
  * The use of real examples to illustrate the explanations, instead of using abstract concepts.
  * The old [Managing Releases](http://symfony.com/doc/current/contributing/documentation/overview.html#managing-releases) section has been completely removed. This has nothing to do with contributing documentations. It's just documentation for a process that only concerns to doc maintainers.

Commits
-------

88ddbb1 Fixed all the errors found by Ryan
baa06b5 Removed two highlight formats which are "experimental" and not used by end users
9bcd33d More and more fixes and improvements
15f3c94 Added another bunch of fixes suggested by reviewers
ff66e94 Added lots of fixes suggested by reviewers
991ff6f Added a note about not using relative internal links in the doc
79375ae Switched another relative link into an absolute reference
4751eb9 lways use absolute links instead of relative for internal doc links
53c3a16 Added missing link
723603c Revamped the documentation about "Contributing Docs"
  • Loading branch information...
weaverryan committed Sep 16, 2014
2 parents c567707 + 88ddbb1 commit a578de99b2ba4a83605a530a76111a4cf4daf1fa
@@ -1,17 +1,19 @@
Documentation Format
====================
The Symfony 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 Symfony `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::
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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``
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/
@@ -3,8 +3,8 @@
Symfony Documentation License
=============================
The Symfony documentation is licensed under a Creative Commons
Attribution-Share Alike 3.0 Unported `License`_.
The Symfony2 documentation is licensed under a Creative Commons
Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_).
**You are free:**
@@ -48,5 +48,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
Oops, something went wrong.

0 comments on commit a578de9

Please sign in to comment.