From 5195058abb4f2d54d9890d286be6404408dda6a2 Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Thu, 12 May 2022 23:33:53 +0200 Subject: [PATCH 1/2] Add a Github Action to lint the docs --- .doctor-rst.yaml | 74 ++++++++++++++++++++++++++++++++++++++ .github/workflows/docs.yml | 33 +++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 .doctor-rst.yaml create mode 100644 .github/workflows/docs.yml diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml new file mode 100644 index 0000000..b22ff8c --- /dev/null +++ b/.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' \ No newline at end of file diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..21ccfd7 --- /dev/null +++ b/.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 From 7bc9462e7ec0a35b46ef940116a6b05d78e5f3ea Mon Sep 17 00:00:00 2001 From: Guilhem Niot Date: Thu, 12 May 2022 23:48:13 +0200 Subject: [PATCH 2/2] Fix DOCtor-RST errors --- Resources/doc/areas.rst | 2 +- Resources/doc/commands.rst | 12 ++++++------ Resources/doc/faq.rst | 6 +++--- Resources/doc/index.rst | 8 ++++---- Resources/doc/security.rst | 2 +- UPGRADE-3.0.md | 2 +- 6 files changed, 16 insertions(+), 16 deletions(-) diff --git a/Resources/doc/areas.rst b/Resources/doc/areas.rst index e1f0f08..ca0696c 100644 --- a/Resources/doc/areas.rst +++ b/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 diff --git a/Resources/doc/commands.rst b/Resources/doc/commands.rst index 67ab295..fb54519 100644 --- a/Resources/doc/commands.rst +++ b/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/ diff --git a/Resources/doc/faq.rst b/Resources/doc/faq.rst index 439dfb5..53c901c 100644 --- a/Resources/doc/faq.rst +++ b/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 diff --git a/Resources/doc/index.rst b/Resources/doc/index.rst index 6bc43bd..69873b7 100644 --- a/Resources/doc/index.rst +++ b/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:: diff --git a/Resources/doc/security.rst b/Resources/doc/security.rst index a812e59..aa743ea 100644 --- a/Resources/doc/security.rst +++ b/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 diff --git a/UPGRADE-3.0.md b/UPGRADE-3.0.md index a39c300..f720e27 100644 --- a/UPGRADE-3.0.md +++ b/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.