Merge remote-tracking branch 'origin/master' into constraint_groups

.doctor-rst.yaml

@@ -0,0 +1,74 @@
+rules:
+    american_english: ~
+    avoid_repetetive_words: ~
+    blank_line_after_anchor: ~
+    blank_line_after_directive: ~
+    blank_line_before_directive: ~
+    composer_dev_option_not_at_the_end: ~
+    correct_code_block_directive_based_on_the_content: ~
+    deprecated_directive_should_have_version: ~
+    ensure_exactly_one_space_between_link_definition_and_link: ~
+    ensure_link_definition_contains_valid_url: ~
+    ensure_order_of_code_blocks_in_configuration_block: ~
+    extend_abstract_controller: ~
+    extension_xlf_instead_of_xliff: ~
+    indention: ~
+    lowercase_as_in_use_statements: ~
+    max_blank_lines:
+        max: 2
+    max_colons: ~
+    no_app_console: ~
+    no_blank_line_after_filepath_in_php_code_block: ~
+    no_blank_line_after_filepath_in_twig_code_block: ~
+    no_blank_line_after_filepath_in_xml_code_block: ~
+    no_blank_line_after_filepath_in_yaml_code_block: ~
+    no_brackets_in_method_directive: ~
+    no_composer_req: ~
+    no_directive_after_shorthand: ~
+    no_explicit_use_of_code_block_php: ~
+    no_inheritdoc: ~
+    no_namespace_after_use_statements: ~
+    no_php_open_tag_in_code_block_php_directive: ~
+    no_space_before_self_xml_closing_tag: ~
+    only_backslashes_in_namespace_in_php_code_block: ~
+    only_backslashes_in_use_statements_in_php_code_block: ~
+    ordered_use_statements: ~
+    php_prefix_before_bin_console: ~
+    replace_code_block_types: ~
+    replacement: ~
+    short_array_syntax: ~
+    space_between_label_and_link_in_doc: ~
+    space_between_label_and_link_in_ref: ~
+    string_replacement: ~
+    typo: ~
+    unused_links: ~
+    use_deprecated_directive_instead_of_versionadded: ~
+    use_https_xsd_urls: ~
+    valid_inline_highlighted_namespaces: ~
+    valid_use_statements: ~
+    versionadded_directive_should_have_version: ~
+    yaml_instead_of_yml_suffix: ~
+    yarn_dev_option_at_the_end: ~
+#    no_app_bundle: ~
+
+    #   master
+    versionadded_directive_major_version:
+        major_version: 5
+
+    versionadded_directive_min_version:
+        min_version: '5.0'
+
+    deprecated_directive_major_version:
+        major_version: 5
+
+    deprecated_directive_min_version:
+        min_version: '5.0'
+
+# do not report as violation
+whitelist:
+    regex:
+        - '/``.yml``/'
+    lines:
+        - '.. code-block:: twig'
+        - '// bin/console'
+        - '.. code-block:: php'

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+    push: ~
+    pull_request: ~
+
+jobs:
+    doctor-rst:
+        name: Lint (DOCtor-RST)
+
+        runs-on: ubuntu-latest
+
+        steps:
+            -   name: "Checkout"
+                uses: actions/checkout@v2
+
+            -   name: "Create cache dir"
+                run: mkdir .cache
+
+            -   name: "Extract base branch name"
+                run: echo "##[set-output name=branch;]$(echo ${GITHUB_BASE_REF:=${GITHUB_REF##*/}})"
+                id: extract_base_branch
+
+            -   name: "Cache DOCtor-RST"
+                uses: actions/cache@v2
+                with:
+                    path: .cache
+                    key: ${{ runner.os }}-doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
+
+            -   name: "Run DOCtor-RST"
+                uses: docker://oskarstark/doctor-rst
+                with:
+                    args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache

Resources/doc/areas.rst

@@ -40,7 +40,7 @@ Then update your routing to be able to access your different documentations:
 
 .. code-block:: yaml
 
-    # app/config/routing.yml
+    # app/config/routing.yaml
     app.swagger_ui:
         path: /api/doc/{area}
         methods: GET

Resources/doc/commands.rst

@@ -5,7 +5,7 @@ A command is provided in order to dump the documentation in ``json``, ``yaml`` o
 
 .. code-block:: bash
 
-    $ php app/console nelmio:apidoc:dump [--format="..."]
+    $ php bin/console nelmio:apidoc:dump [--format="..."]
 
 The ``--format`` option allows to choose the format (default is: ``json``).
 
@@ -14,20 +14,20 @@ without whitespace, use the ``--no-pretty`` option.
 
 .. code-block:: bash
 
-    $ php app/console nelmio:apidoc:dump --format=json > json-pretty-formatted.json
-    $ php app/console nelmio:apidoc:dump --format=json --no-pretty > json-no-pretty.json
+    $ php bin/console nelmio:apidoc:dump --format=json > json-pretty-formatted.json
+    $ php bin/console nelmio:apidoc:dump --format=json --no-pretty > json-no-pretty.json
 
 Every format can override API url. Useful if static documentation is not hosted on API url:
 
 .. code-block:: bash
 
-    $ php app/console nelmio:apidoc:dump --format=yaml --server-url "http://example.com/api" > api.yaml
+    $ php bin/console nelmio:apidoc:dump --format=yaml --server-url "http://example.com/api" > api.yaml
 
 For example to generate a static version of your documentation you can use:
 
 .. code-block:: bash
 
-    $ php app/console nelmio:apidoc:dump --format=html > api.html
+    $ php bin/console nelmio:apidoc:dump --format=html > api.html
 
 By default, the generated HTML will add the sandbox feature.
 If you want to generate a static version of your documentation without sandbox,
@@ -40,6 +40,6 @@ or configure UI configuration, use the ``--html-config`` option.
 
 .. code-block:: bash
 
-    $ php app/console nelmio:apidoc:dump --format=html --html-config '{"assets_mode":"offline","server_url":"https://example.com","swagger_ui_config":{"supportedSubmitMethods":[]}}' > api.html
+    $ php bin/console nelmio:apidoc:dump --format=html --html-config '{"assets_mode":"offline","server_url":"https://example.com","swagger_ui_config":{"supportedSubmitMethods":[]}}' > api.html
 
 .. _`configure Swagger UI`: https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/

Resources/doc/faq.rst

@@ -10,7 +10,7 @@ A: You can configure ``schemas`` in the nelmio_api_doc configuration and then re
 
 .. code-block:: yaml
 
-    # config/nelmio_api_doc.yml
+    # config/nelmio_api_doc.yaml
     nelmio_api_doc:
         documentation:
             components:
@@ -125,7 +125,7 @@ If you have not set up this script, you can manually execute this command:
 
 .. code-block:: bash
 
-    $ bin/console assets:install --symlink
+    $ php bin/console assets:install --symlink
 
 Re-add Google Fonts
 -------------------
@@ -194,7 +194,7 @@ A: Use ``@OA\Tag`` annotation.
      */
     class BookmarkController extends AbstractFOSRestController implements ContextPresetInterface
     {
-        //...
+        // ...
     }
 
 Disable Default Section

Resources/doc/index.rst

@@ -8,7 +8,7 @@ What's supported?
 -----------------
 
 This bundle supports *Symfony* route requirements, PHP annotations, `Swagger-Php`_ annotations,
-`FOSRestBundle`_ annotations and apps using `Api-Platform`_.
+`FOSRestBundle`_ annotations and applications using `Api-Platform`_.
 
 .. _`Swagger-Php`: https://github.com/zircote/swagger-php
 .. _`FOSRestBundle`: https://github.com/FriendsOfSymfony/FOSRestBundle
@@ -145,8 +145,8 @@ To document your routes, you can use the SwaggerPHP annotations and the
     
         namespace AppBundle\Controller;
 
-        use AppBundle\Entity\User;
         use AppBundle\Entity\Reward;
+        use AppBundle\Entity\User;
         use Nelmio\ApiDocBundle\Annotation\Model;
         use Nelmio\ApiDocBundle\Annotation\Security;
         use OpenApi\Annotations as OA;
@@ -187,8 +187,8 @@ To document your routes, you can use the SwaggerPHP annotations and the
     
         namespace AppBundle\Controller;
 
-        use AppBundle\Entity\User;
         use AppBundle\Entity\Reward;
+        use AppBundle\Entity\User;
         use Nelmio\ApiDocBundle\Annotation\Model;
         use Nelmio\ApiDocBundle\Annotation\Security;
         use OpenApi\Attributes as OA;
@@ -225,7 +225,7 @@ To document your routes, you can use the SwaggerPHP annotations and the
         }
     
 
-The normal PHPdoc block on the controller method is used for the summary and description.
+The normal PHPDoc block on the controller method is used for the summary and description.
 
 .. tip::
 

Resources/doc/security.rst

@@ -24,7 +24,7 @@ This will add the Bearer security policy to all registered paths.
 Overriding Specific Paths
 -------------------------
 
-The security policy can be overriden for a path using the ``@Security`` annotation.
+The security policy can be overridden for a path using the ``@Security`` annotation.
 
 .. code-block:: php
 

UPGRADE-3.0.md

@@ -230,7 +230,7 @@ class SwaggerDocblockConvertCommand extends ContainerAwareCommand
 Then open a command console, enter your project directory and run:
 
 ```
-bin/console api:doc:convert
+php bin/console api:doc:convert
 ```
 
 Your annotations should all be converted.