Merge pull request #814 from javiereguiluz/fix_813

Transformed documentation to RST format

Resources/doc/commands.rst

@@ -0,0 +1,21 @@
+Commands
+========
+
+A command is provided in order to dump the documentation in ``json``, ``markdown``,
+or ``html``.
+
+.. code-block:: bash
+
+    $ php app/console api:doc:dump [--format="..."]
+
+The ``--format`` option allows to choose the format (default is: ``markdown``).
+
+For example to generate a static version of your documentation you can use:
+
+.. code-block:: bash
+
+    $ php app/console api:doc:dump --format=html > api.html
+
+By default, the generated HTML will add the sandbox feature if you didn't
+disable it in the configuration.  If you want to generate a static version of
+your documentation without sandbox, use the ``--no-sandbox`` option.

Resources/doc/configuration-in-depth.rst

@@ -0,0 +1,132 @@
+Configuration In-Depth
+======================
+
+API Name
+--------
+
+You can specify your own API name:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        name: My API
+
+Authentication Methods
+----------------------
+
+You can choose between different authentication methods:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        sandbox:
+            authentication:
+                delivery: header
+                name:     X-Custom
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        sandbox:
+            authentication:
+                delivery: query
+                name:     param
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        sandbox:
+            authentication:
+                delivery: http
+                type:     basic # or bearer
+
+When choosing an ``http`` delivery, ``name`` defaults to ``Authorization``, and
+the header value will automatically be prefixed by the corresponding type (ie.
+``Basic`` or ``Bearer``).
+
+Section Exclusion
+-----------------
+
+You can specify which sections to exclude from the documentation generation:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        exclude_sections: ["privateapi", "testapi"]
+
+Note that ``exclude_sections`` will literally exclude a section from your api
+documentation. It's possible however to create multiple views by specifying the
+``views`` parameter within the ``@ApiDoc`` annotations. This allows you to move
+private or test methods to a complete different view of your documentation
+instead.
+
+Parsers
+-------
+
+By default, all registered parsers are used, but sometimes you may want to
+define which parsers you want to use. The ``parsers`` attribute is used to
+configure a list of parsers that will be used::
+
+    output={
+        "class"   = "Acme\Bundle\Entity\User",
+        "parsers" = {
+            "Nelmio\ApiDocBundle\Parser\JmsMetadataParser",
+            "Nelmio\ApiDocBundle\Parser\ValidationParser"
+        }
+    }
+
+In this case the parsers ``JmsMetadataParser`` and ``ValidationParser`` are used
+to generate returned data. This feature also works for both the ``input`` and
+``output`` properties.
+
+Moreover, the bundle provides a way to register multiple ``input`` parsers. The
+first parser that can handle the specified input is used, so you can configure
+their priorities via container tags. Here's an example parser service
+registration:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    services:
+        mybundle.api_doc.extractor.custom_parser:
+            class: MyBundle\Parser\CustomDocParser
+            tags:
+                - { name: nelmio_api_doc.extractor.parser, priority: 2 }
+
+MOTD
+----
+
+You can also define your own motd content (above methods list). All you have to
+do is add to configuration:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        # ...
+        motd:
+            template: AcmeApiBundle::Components/motd.html.twig
+
+Caching
+-------
+
+It is a good idea to enable the internal caching mechanism on production:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        cache:
+            enabled: true
+
+You can define an alternate location where the ApiDoc configurations are to be
+cached:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    nelmio_api_doc:
+        cache:
+            enabled: true
+            file: "/tmp/symfony-app/%kernel.environment%/api-doc.cache"