minor #775 Add RST Linter (DOCtor-RST) to the CI config (bocharsky-bw)

This PR was squashed before being merged into the 2.x branch.

Discussion
----------

Add RST Linter (DOCtor-RST) to the CI config

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Tickets       |  <!-- prefix each issue number with "Fix #", no need to create an issue if none exist, explain below instead -->
| License       | MIT

Symfony Docs use it, would be great to reuse it here as well

### TODO
- [x] Add more rules

Seems it was pretty useful looking at the changes diff :)

Commits
-------

4ce9ec7 Add RST Linter (DOCtor-RST) to the CI config

Author: weaverryan

.doctor-rst.yaml

@@ -0,0 +1,96 @@
+rules:
+    american_english: ~
+    argument_variable_must_match_type: ~
+    avoid_repetetive_words: ~
+#    be_kind_to_newcomers: ~
+    blank_line_after_anchor: ~
+#    blank_line_after_colon: ~
+    blank_line_after_directive: ~
+#    blank_line_after_filepath_in_code_block: ~
+#    blank_line_after_filepath_in_php_code_block: ~
+#    blank_line_after_filepath_in_twig_code_block: ~
+#    blank_line_after_filepath_in_xml_code_block: ~
+#    blank_line_after_filepath_in_yaml_code_block: ~
+    blank_line_before_directive: ~
+#    composer_dev_option_at_the_end: ~
+    composer_dev_option_not_at_the_end: ~
+    correct_code_block_directive_based_on_the_content: ~
+    deprecated_directive_major_version:
+        major_version: 2
+    deprecated_directive_min_version:
+        min_version: '2.0'
+    deprecated_directive_should_have_version: ~
+    ensure_bash_prompt_before_composer_command: ~
+    ensure_exactly_one_space_before_directive_type: ~
+    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_admin: ~
+    extend_abstract_controller: ~
+#    extend_controller: ~
+    extension_xlf_instead_of_xliff: ~
+#    filename_uses_dashes_only: ~
+#    filename_uses_underscores_only: ~
+    final_admin_classes: ~
+    final_admin_extension_classes: ~
+    forbidden_directives:
+        directives:
+            - '.. index::'
+    indention: ~
+    kernel_instead_of_app_kernel: ~
+#    line_length: ~
+    lowercase_as_in_use_statements: ~
+    max_blank_lines:
+        max: 2
+    max_colons: ~
+    no_admin_yaml: ~
+    no_app_bundle: ~
+    no_app_console: ~
+#    no_bash_prompt: ~
+    no_blank_line_after_filepath_in_code_block: ~
+    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_phar: ~
+    no_composer_req: ~
+    no_config_yaml: ~
+#    no_contraction: ~
+    no_directive_after_shorthand: ~
+    no_explicit_use_of_code_block_php: ~
+    no_inheritdoc_in_code_examples: ~
+    no_merge_conflict: ~
+    no_namespace_after_use_statements: ~
+    no_php_open_tag_in_code_block_php_directive: ~
+#    no_php_prefix_before_bin_console: ~
+#    no_php_prefix_before_composer: ~
+    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_open_tag_in_code_block_php_directive: ~
+    php_prefix_before_bin_console: ~
+    replace_code_block_types: ~
+    replacement: ~
+    short_array_syntax: ~
+#    space_before_self_xml_closing_tag: ~
+    space_between_label_and_link_in_doc: ~
+    space_between_label_and_link_in_ref: ~
+    string_replacement: ~
+    title_underline_length_must_match_title_length: ~
+    typo: ~
+    unused_links: ~
+    use_deprecated_directive_instead_of_versionadded: ~
+    use_https_xsd_urls: ~
+#    use_named_constructor_without_new_keyword_rule: ~
+    valid_inline_highlighted_namespaces: ~
+    valid_use_statements: ~
+    versionadded_directive_major_version:
+        major_version: 2
+    versionadded_directive_min_version:
+        min_version: '2.0'
+    versionadded_directive_should_have_version: ~
+    yaml_instead_of_yml_suffix: ~
+    yarn_dev_option_at_the_end: ~
+#    yarn_dev_option_not_at_the_end: ~

.github/workflows/doctor-rst.yaml

@@ -0,0 +1,31 @@
+name: RST Linter
+
+on:
+    push:
+    pull_request:
+
+jobs:
+    doctor-rst:
+        name: DOCtor-RST
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v3
+
+            - 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@v3
+              with:
+                  path: .cache
+                  key: doctor-rst-${{ steps.extract_base_branch.outputs.branch }}
+
+            - name: DOCtor-RST
+              uses: docker://oskarstark/doctor-rst
+              with:
+                  args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache

.github/workflows/test.yaml

@@ -1,6 +1,8 @@
 name: Symfony UX
 
-on: [push, pull_request]
+on:
+    push:
+    pull_request:
 
 jobs:
     coding-style-php:

.gitignore

@@ -1,3 +1,4 @@
+.doctor-rst.cache
 .php-cs-fixer.cache
 node_modules
 yarn.lock

src/Autocomplete/doc/index.rst

@@ -303,7 +303,6 @@ To use another route, first declare it:
 Then specify this new route on the attribute::
 
     // src/Form/FoodAutocompleteField.php
-
     #[AsEntityAutocompleteField(route: 'ux_entity_autocomplete_admin')]
     class FoodAutocompleteField
     // ...
@@ -470,7 +469,7 @@ This library comes with a Stimulus controller that can activate
 Tom Select on any ``select`` or ``input`` element. This can be used
 outside of the Form component. For example:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <select
         name="food"
@@ -481,7 +480,7 @@ That's it! If you want the options to be autocompleted via
 Ajax, pass a ``url`` value, which works well if you create
 a :ref:`custom autocompleter <custom-autocompleter>`:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <select
         name="food"

src/Chartjs/doc/index.rst

@@ -77,7 +77,7 @@ All options and data are provided as-is to Chart.js. You can read
 Once created in PHP, a chart can be displayed using Twig if installed
 (requires `Symfony Webpack Encore`_):
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     {{ render_chart(chart) }}
 

src/Cropperjs/doc/index.rst

@@ -35,8 +35,8 @@ create a Crop object, and use this object inside a standard form::
 
     // ...
     use Symfony\Component\HttpFoundation\Request;
-    use Symfony\UX\Cropperjs\Form\CropperType;
     use Symfony\UX\Cropperjs\Factory\CropperInterface;
+    use Symfony\UX\Cropperjs\Form\CropperType;
 
     class HomeController extends AbstractController
     {

src/Dropzone/doc/index.rst

@@ -80,6 +80,7 @@ switching the ``@symfony/ux-dropzone/src/style.css`` autoimport to
     }
 
 .. note::
+
    *Note*: you should put the value to ``false`` and not remove the line
    so that Symfony Flex won’t try to add the line again in the future.
 

src/LazyImage/doc/index.rst

@@ -38,7 +38,7 @@ The default usage of Symfony UX LazyImage is to use its Stimulus
 controller to first load a small placeholder image that will then be
 replaced by the high-definition version once the page has been rendered:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <img
         src="{{ asset('image/small.png') }}"
@@ -58,7 +58,7 @@ larger image, the ``src`` attribute will change to ``image/large.png``.
 There is also support for the ``srcset`` attribute by passing an
 ``srcset`` value to the controller:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <img
         src="{{ asset('image/small.png') }}"
@@ -81,7 +81,7 @@ Instead of using a generated thumbnail that would exist on your
 filesystem, you can use the BlurHash algorithm to create a light,
 blurred, data-uri thumbnail of the image:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <img
         src="{{ data_uri_thumbnail('public/image/large.png', 100, 75) }}"
@@ -140,7 +140,7 @@ custom Stimulus controller:
 
 Then in your template, add your controller to the HTML attribute:
 
-.. code-block:: twig
+.. code-block:: html+twig
 
     <img
         src="{{ data_uri_thumbnail('public/image/large.png', 100, 75) }}"
@@ -158,9 +158,9 @@ Then in your template, add your controller to the HTML attribute:
 
 ..
 
-   **Note**: be careful to add your controller **before** the LazyImage
-   controller so that it is executed before and can listen on the
-   ``lazy-image:connect`` event properly.
+    **Note**: be careful to add your controller **before** the LazyImage
+    controller so that it is executed before and can listen on the
+    ``lazy-image:connect`` event properly.
 
 Backward Compatibility promise
 ------------------------------