Documentation Format ¶
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 a plain text 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 source code.
If you want to learn more about this format, check out the reStructuredText Primer tutorial and the reStructuredText Reference.
Caution
If you are familiar with Markdown, be careful as things are sometimes very similar but different:
- Lists starts at the beginning of a line (no indentation is allowed);リストは行頭から始まります (インデントは許可されません)。
- Inline code blocks use double-ticks (
``like this``).インラインコードブロックはダブルティックを使用します (``like this``)。
Sphinx ¶
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 reStructuredText markup. Read more about the Sphinx Markup Constructs.
Syntax Highlighting ¶
PHP is the default syntax highlighter applied to all code blocks. You can
change it with the code-block directive:
1 2 3 |
.. code-block:: yaml
{ foo: bar, bar: { foo: bar, bar: baz } }
|
Note
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.
Configuration Blocks ¶
Whenever you include a configuration sample, use the configuration-block
directive to show the configuration in all supported configuration formats
(PHP, YAML and XML). Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 |
.. configuration-block::
.. code-block:: yaml
# Configuration in YAML
.. code-block:: xml
<!-- Configuration in XML -->
.. code-block:: php
// Configuration in PHP
|
The previous reStructuredText snippet renders as follow:
-
YAML
YAML
-
XML
XML
-
PHP
PHP
1 |
# Configuration in YAML
|
The current list of supported formats are the following:
| Markup Format | Use It to Display |
|---|---|
html |
HTML |
xml |
XML |
php |
PHP |
yaml |
YAML |
twig |
Pure Twig markup |
html+twig |
Twig markup blended with HTML |
html+php |
PHP code blended with HTML |
ini |
INI |
php-annotations |
PHP Annotations |
php-attributes |
PHP Attributes |
Adding Links ¶
The most common type of links are internal links to other documentation pages, which use the following syntax:
1 |
:doc:`/absolute/path/to/page`
|
The page name should not include the file extension (.rst). For example:
1 2 3 4 5 |
:doc:`/controller`
:doc:`/components/event_dispatcher`
:doc:`/configuration/environments`
|
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:
1 |
:doc:`Doctrine Associations </doctrine/associations>`
|
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:
1 2 3 4 5 |
:doc:`controller`
:doc:`event_dispatcher`
:doc:`environments`
|
Links to the API follow a different syntax, where you must specify the type
of the linked resource (class or method):
1 2 3 |
:class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`
:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`
|
Links to the PHP documentation follow a pretty similar syntax:
1 2 3 4 5 |
:phpclass:`SimpleXMLElement`
:phpmethod:`DateTime::createFromFormat`
:phpfunction:`iterator_to_array`
|
New Features, Behavior Changes or Deprecations ¶
If you are documenting a brand new feature, a change or a deprecation that's been made in Symfony, you should precede your description of the change with the corresponding directive and a short description:
For a new feature or a behavior change use the .. versionadded:: 6.x
directive:
1 2 3 |
.. versionadded:: 6.2
... ... ... was introduced in Symfony 6.2.
|
If you are documenting a behavior change, it may be helpful to briefly describe how the behavior has changed:
1 2 3 4 |
.. versionadded:: 6.2
... ... ... was introduced in Symfony 6.2. Prior to this,
... ... ... ... ... ... ... ... .
|
For a deprecation use the .. deprecated:: 6.x directive:
1 2 3 |
.. deprecated:: 6.2
... ... ... was deprecated in Symfony 6.2.
|
Whenever a new major version of Symfony is released (e.g. 6.0, 7.0, etc), a new
branch of the documentation is created from the x.4 branch of the previous
major version. At this point, all the versionadded and deprecated tags
for Symfony versions that have a lower major version will be removed. For
example, if Symfony 6.0 were released today, 5.0 to 5.4 versionadded and
deprecated tags would be removed from the new 6.0 branch.