Merge pull request symfony#1663 from richardmiller/adding_info_on_links_in_docs

weaverryan · weaverryan · commit c4677e10dbd9 · 2012-09-01T18:48:36.000-07:00
Adding some information on adding links within the documentation
diff --git a/contributing/documentation/format.rst b/contributing/documentation/format.rst
@@ -119,6 +119,50 @@ The current list of supported formats are the following:
 | php-annotations | Annotations |
 +-----------------+-------------+
 
+Adding Links
+~~~~~~~~~~~~
+
+To add links to other pages in the documents use the following syntax:
+
+.. code-block:: rst
+
+    :doc:`/path/to/page`
+
+Using the path and filename of the page without the extension, for example:
+
+.. code-block:: rst
+
+    :doc:`/book/controller`
+
+    :doc:`/components/event_dispatcher/introduction`
+
+    :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:
+
+.. code-block:: rst
+
+    :doc:`Spooling Email</cookbook/email/spool>`
+
+You can also add links to the API documentation:
+
+.. code-block:: rst
+
+    :class:`Symfony\\Component\\Routing\\Matcher\\ApacheUrlMatcher`
+
+    :method:`Symfony\\Component\\HttpKernel\\Bundle\\Bundle::build`
+
+and to the PHP documentation:
+
+.. code-block:: rst
+
+    :phpclass:`SimpleXMLElement`
+
+    :phpmethod:`DateTime::createFromFormat`
+
+    :phpfunction:`iterator_to_array`
+
 Testing Documentation
 ~~~~~~~~~~~~~~~~~~~~~
 
