Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commita578de9

Browse files
committed
feature#4223 Revamped the documentation about "Contributing Docs" (javiereguiluz)
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 Ryanbaa06b5 Removed two highlight formats which are "experimental" and not used by end users9bcd33d More and more fixes and improvements15f3c94 Added another bunch of fixes suggested by reviewersff66e94 Added lots of fixes suggested by reviewers991ff6f Added a note about not using relative internal links in the doc79375ae Switched another relative link into an absolute reference4751eb9 lways use absolute links instead of relative for internal doc links53c3a16 Added missing link723603c Revamped the documentation about "Contributing Docs"
2 parentsc567707 +88ddbb1 commita578de9

File tree

5 files changed

+356
-214
lines changed

5 files changed

+356
-214
lines changed
Lines changed: 103 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,19 @@
11
Documentation Format
22
====================
33

4-
The Symfony documentation uses `reStructuredText`_ as its markup language and
5-
`Sphinx`_ for building the output (HTML, PDF, ...).
4+
The Symfony documentation usesreStructuredText_ as its markup language and
5+
Sphinx_ for generating the documentation in the formats read by the end users,
6+
such as HTML and PDF.
67

78
reStructuredText
89
----------------
910

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

13-
You canlearn more aboutits syntax by reading existing Symfony `documents`_
14-
or by readingthe `reStructuredTextPrimer`_ on the Sphinx website.
15+
If you want tolearn more aboutthis format, check out the `reStructuredText Primer`_
16+
tutorial andthe `reStructuredTextReference`_.
1517

1618
..caution::
1719

@@ -24,14 +26,14 @@ or by reading the `reStructuredText Primer`_ on the Sphinx website.
2426
Sphinx
2527
------
2628

27-
Sphinx is a build system thatadds some nicetools to create documentation
28-
fromreStructuredText documents. As such, it adds new directives and
29-
interpreted textroles to the standard reST`markup`_.
29+
Sphinx is a build system thatprovidestools to create documentation from
30+
reStructuredText documents. As such, it adds new directives and interpreted text
31+
roles to the standard reST markup. Read more about the `Sphinx Markup Constructs`_.
3032

3133
Syntax Highlighting
3234
~~~~~~~~~~~~~~~~~~~
3335

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

3739
..code-block::rst
@@ -41,7 +43,7 @@ it with the ``code-block`` directive:
4143
{ foo: bar, bar: { foo: bar, bar: baz } }
4244
4345
If your PHP code begins with ``<?php``, then you need to use ``html+php`` as
44-
the highlightedpseudo-language:
46+
thename of thehighlightedsyntax:
4547

4648
..code-block::rst
4749
@@ -51,16 +53,18 @@ the highlighted pseudo-language:
5153
5254
..note::
5355

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

5660
.. _docs-configuration-blocks:
5761

5862
Configuration Blocks
5963
~~~~~~~~~~~~~~~~~~~~
6064

61-
Whenever youshow a configuration, you must use the ``configuration-block``
65+
Whenever youinclude a configuration sample, use the ``configuration-block``
6266
directive to show the configuration in all supported configuration formats
63-
(``PHP``, ``YAML``, and ``XML``)
67+
(``PHP``, ``YAML`` and ``XML``). Example:
6468

6569
..code-block::rst
6670
@@ -96,32 +100,31 @@ The previous reST snippet renders as follow:
96100
97101
The current list of supported formats are the following:
98102

99-
=============== ==============
100-
Markup format Displayed
101-
=============== ==============
102-
html HTML
103-
xml XML
104-
php PHP
105-
yaml YAML
106-
jinja Twig
107-
html+jinja Twig
108-
html+php PHP
109-
ini INI
110-
php-annotations Annotations
111-
php-standalone Standalone Use
112-
php-symfony Framework Use
113-
=============== ==============
103+
=================== ======================================
104+
Markup format Use it to display
105+
=================== ======================================
106+
``html`` HTML
107+
``xml`` XML
108+
``php`` PHP
109+
``yaml`` YAML
110+
``jinja`` Pure Twig markup
111+
``html+jinja`` Twig markup blended with HTML
112+
``html+php`` PHP code blended with HTML
113+
``ini`` INI
114+
``php-annotations`` PHP Annotations
115+
=================== ======================================
114116

115117
Adding Links
116118
~~~~~~~~~~~~
117119

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

120123
..code-block::rst
121124
122-
:doc:`/path/to/page`
125+
:doc:`/absolute/path/to/page`
123126
124-
Using the path and filename of thepage without theextension, for example:
127+
The page name should not include thefileextension (``.rst``). For example:
125128

126129
..code-block::rst
127130
@@ -131,14 +134,29 @@ Using the path and filename of the page without the extension, for example:
131134
132135
:doc:`/cookbook/configuration/environments`
133136
134-
Thelink textwill bethe main heading ofthedocument linked to. You can
135-
also specify alternative text for the link:
137+
Thetitle of the linked pagewill beautomatically used asthetext of the link.
138+
If you want to modify that title, use this alternative syntax:
136139

137140
..code-block::rst
138141
139142
:doc:`Spooling Email </cookbook/email/spool>`
140143
141-
You can also add links to the API documentation:
144+
..note::
145+
146+
Although they are technically correct, avoid the use of relative internal
147+
links such as the following, because they break the references in the
148+
generated PDF documentation:
149+
150+
..code-block::rst
151+
152+
:doc:`controller`
153+
154+
:doc:`event_dispatcher/introduction`
155+
156+
:doc:`environments`
157+
158+
**Links to the API** follow a different syntax, where you must specify the type
159+
of the linked resource (``namespace``, ``class`` or ``method``):
142160

143161
..code-block::rst
144162
@@ -148,7 +166,7 @@ You can also add links to the API documentation:
148166
149167
:method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`
150168
151-
and to the PHP documentation:
169+
**Links to the PHP documentation** follow a pretty similar syntax:
152170

153171
..code-block::rst
154172
@@ -158,20 +176,55 @@ and to the PHP documentation:
158176
159177
:phpfunction:`iterator_to_array`
160178
161-
Testing Documentation
162-
~~~~~~~~~~~~~~~~~~~~~
179+
New Features or Behavior Changes
180+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
163181

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

166-
* Install `Sphinx`_;
167-
* Install the Sphinx extensions using git submodules: ``git submodule update --init``;
168-
* (Optionally) Install the bundle docs and CMF docs: ``bash install.sh``;
169-
* Run ``make html`` and view the generated HTML in the ``build`` directory.
186+
..code-block::text
187+
188+
.. versionadded:: 2.3
189+
The ``askHiddenResponse`` method was introduced in Symfony 2.3.
190+
191+
You can also ask a question and hide the response. This is particularly [...]
192+
193+
If you're documenting a behavior change, it may be helpful to *briefly* describe
194+
how the behavior has changed.
195+
196+
..code-block::text
197+
198+
.. versionadded:: 2.3
199+
The ``include()`` function is a new Twig feature that's available in
200+
Symfony 2.3. Prior, the ``{% include %}`` tag was used.
201+
202+
Whenever a new minor version of Symfony is released (e.g. 2.4, 2.5, etc),
203+
a new branch of the documentation is created from the ``master`` branch.
204+
At this point, all the ``versionadded`` tags for Symfony versions that have
205+
reached end-of-life will be removed. For example, if Symfony 2.5 were released
206+
today, and 2.2 had recently reached its end-of-life, the 2.2 ``versionadded``
207+
tags would be removed from the new 2.5 branch.
208+
209+
Testing Documentation
210+
~~~~~~~~~~~~~~~~~~~~~
170211

171-
.. _reStructuredText:http://docutils.sourceforge.net/rst.html
172-
.. _Sphinx:http://sphinx-doc.org/
173-
.. _documents:https://github.com/symfony/symfony-docs
174-
.. _reStructuredText Primer:http://sphinx-doc.org/rest.html
175-
.. _markup:http://sphinx-doc.org/markup/
176-
.. _Pygments website:http://pygments.org/languages/
177-
.. _Sphinx quick setup:http://sphinx-doc.org/tutorial.html#setting-up-the-documentation-sources
212+
When submitting a new content to the documentation repository or when changing
213+
any existing resource, an automatic process will check if your documentation is
214+
free of syntax errors and is ready to be reviewed.
215+
216+
Nevertheless, if you prefer to do this check locally on your own machine before
217+
submitting your documentation, follow these steps:
218+
219+
* InstallSphinx_;
220+
* Install the Sphinx extensions using git submodules: ``$ git submodule update --init``;
221+
* (Optionally) Install the bundle docs and CMF docs: ``$ bash install.sh``;
222+
* Run ``make html`` and view the generated HTML in the ``build/`` directory.
223+
224+
.. _reStructuredText:http://docutils.sourceforge.net/rst.html
225+
.. _Sphinx:http://sphinx-doc.org/
226+
.. _`Symfony documentation`:https://github.com/symfony/symfony-docs
227+
.. _`reStructuredText Primer`:http://sphinx-doc.org/rest.html
228+
.. _`reStructuredText Reference`:http://docutils.sourceforge.net/docs/user/rst/quickref.html
229+
.. _`Sphinx Markup Constructs`:http://sphinx-doc.org/markup/
230+
.. _`supported languages`:http://pygments.org/languages/

‎contributing/documentation/license.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,8 @@
33
Symfony Documentation License
44
=============================
55

6-
TheSymfony documentation is licensed under a Creative Commons
7-
Attribution-Share Alike 3.0 Unported`License`_.
6+
TheSymfony2 documentation is licensed under a Creative Commons
7+
Attribution-Share Alike 3.0 Unported License (`CC BY-SA 3.0`_).
88

99
**You are free:**
1010

@@ -48,5 +48,5 @@ Attribution-Share Alike 3.0 Unported `License`_.
4848

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

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

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp