diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst index e581d0382e4..ef17b55011e 100644 --- a/contributing/documentation/format.rst +++ b/contributing/documentation/format.rst @@ -2,19 +2,17 @@ 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. +a custom tool called `Docs Builder`_ for generating the documentation pages. 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. +stricter with its syntax. If you are new to reStructuredText, check out the +`reStructuredText Primer`_ tutorial and the `reStructuredText Reference`_. -If you want to learn more about this format, check out the `reStructuredText Primer`_ -tutorial and the `reStructuredText Reference`_. +You can also take some time to familiarize with this format by reading the +existing `Symfony documentation`_ source. .. warning:: @@ -24,12 +22,11 @@ tutorial and the `reStructuredText Reference`_. * Lists start at the beginning of a line (no indentation is allowed); * Inline code blocks use double-ticks (````like this````). -Sphinx ------- +Custom reStructuredText Directives +---------------------------------- -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`_. +The Symfony documentation includes several custom directives that extend the +standard reStructuredText syntax. Syntax Highlighting ~~~~~~~~~~~~~~~~~~~ @@ -45,9 +42,9 @@ change it with the ``code-block`` directive: .. 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. + Code highlighting is supported for all programming languages commonly used + in Symfony Docs, such as ``yaml``, ``xml``, ``twig``, ``html``, ``js``, + ``json``, ``text``, ``bash``, ``diff``, etc. .. _docs-configuration-blocks: @@ -280,10 +277,8 @@ 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. -.. _reStructuredText: https://docutils.sourceforge.io/rst.html -.. _Sphinx: https://www.sphinx-doc.org/ +.. _`reStructuredText`: https://docutils.sourceforge.io/rst.html +.. _`Docs Builder`: https://github.com/symfony-tools/docs-builder .. _`Symfony documentation`: https://github.com/symfony/symfony-docs .. _`reStructuredText Primer`: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html .. _`reStructuredText Reference`: https://docutils.sourceforge.io/docs/user/rst/quickref.html -.. _`Sphinx Markup Constructs`: https://www.sphinx-doc.org/en/1.7/markup/index.html -.. _`supported languages`: https://pygments.org/languages/