First attempt to add Doctor-RST

.github/workflows/linting.yml

@@ -5,46 +5,89 @@ on:
 jobs:
   prose:
     runs-on: ubuntu-22.04 # See https://github.com/errata-ai/vale-action/issues/128 before upgrading
+    permissions:
+      contents: read
+      pull-requests: write
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-        cache: 'pip'
-
-    - name: Install Python dependencies
-      run: pip3 install -r docs/requirements.txt
-
-    - name: Vale
-      uses: errata-ai/vale-action@reviewdog
-      with:
-        # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
-        version: 3.7.1
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
+
+      - name: Install Python dependencies
+        run: pip3 install -r docs/requirements.txt
+
+      - name: Vale
+        uses: errata-ai/vale-action@reviewdog
+        with:
+          # Please keep version in sync with the version in .gitpod.Dockerfile for a consistent experience
+          version: 3.7.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   build:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout
-      uses: actions/checkout@v4
+      - name: Checkout
+        uses: actions/checkout@v4
 
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.x'
-        cache: 'pip'
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.x'
+          cache: 'pip'
 
-    - name: Install Python dependencies
-      run: pip3 install -r docs/requirements.txt
+      - name: Install Python dependencies
+        run: pip3 install -r docs/requirements.txt
 
-    - name: Build docs
-      working-directory: docs
-      run: make html
+      - name: Build docs
+        working-directory: docs
+        run: make html
+
+      - name: Check links
+        working-directory: docs
+        run: make checklinks
+
+  doctor_rst:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Current Branch
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Ensures full history is fetched
+
+      - name: Extract base branch name
+        id: extract_base_branch
+        run: echo "branch=${GITHUB_BASE_REF:-${GITHUB_REF##*/}}" >> $GITHUB_ENV
+
+      - name: Get changed files
+        id: changed_files
+        run: |
+          git fetch origin ${{ env.branch }}:refs/remotes/origin/${{ env.branch }}
+          git diff --name-only origin/${{ env.branch }}...HEAD > changed_files.txt
+
+      - name: "Create cache dir"
+        run: mkdir .cache
+
+      - name: "Cache DOCtor-RST"
+        uses: actions/cache@v3
+        with:
+          path: .cache
+          key: ${{ runner.os }}-doctor-rst-${{ env.branch }}
 
-    - name: Check links
-      working-directory: docs
-      run: make checklinks
+      - name: "Run DOCtor-RST"
+        env:
+            DOCS_DIR: 'docs/'
+        run: |
+          if [ -s changed_files.txt ]; then
+            xargs -a changed_files.txt docker run --rm -v $(pwd):/github/workspace oskarstark/doctor-rst:1.61.1 --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache
+          else
+            echo "No changed files to analyze."
+          fi
+

docs/.doctor-rst.yaml

@@ -0,0 +1,69 @@
+rules:
+  american_english: ~
+  avoid_repetetive_words: ~
+  be_kind_to_newcomers: ~
+  blank_line_after_anchor: ~
+  blank_line_after_colon: ~
+  blank_line_after_directive: ~
+  blank_line_before_directive: ~
+  blank_line_after_filepath_in_code_block: ~
+  blank_line_after_filepath_in_php_code_block: ~
+  blank_line_after_filepath_in_twig_code_block: ~
+  composer_dev_option_not_at_the_end: ~
+  correct_code_block_directive_based_on_the_content: ~
+  deprecated_directive_should_have_version: ~
+  ensure_bash_prompt_before_composer_command: ~
+  ensure_correct_format_for_phpfunction: ~
+  ensure_exactly_one_space_before_directive_type: ~
+  ensure_exactly_one_space_between_link_definition_and_link: ~
+  ensure_explicit_nullable_types: ~
+  ensure_github_directive_start_with_prefix:
+    prefix: 'Mautic'
+  ensure_link_bottom: ~
+  ensure_link_definition_contains_valid_url: ~
+  ensure_order_of_code_blocks_in_configuration_block: ~
+  ensure_php_reference_syntax: ~
+  extend_abstract_controller: ~
+  filename_uses_underscores_only: ~
+  indention: ~
+  lowercase_as_in_use_statements: ~
+  max_blank_lines:
+    max: 2
+  max_colons: ~
+  no_app_console: ~
+  no_attribute_redundant_parenthesis: ~
+  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_duplicate_use_statements: ~
+  no_footnotes: ~
+  no_inheritdoc: ~
+  no_merge_conflict: ~
+  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: ~
+  remove_trailing_whitespace: ~
+  replace_code_block_types: ~
+  replacement: ~
+  short_array_syntax: ~
+  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_named_constructor_without_new_keyword_rule: ~
+  use_https_xsd_urls: ~
+  valid_inline_highlighted_namespaces: ~
+  valid_use_statements: ~
+  versionadded_directive_should_have_version: ~
+  yaml_instead_of_yml_suffix: ~

docs/companies/companies_overview.rst

@@ -9,7 +9,7 @@ Companies are a way to group Contacts based on association with organizations.
   :alt: Mautic Company Overview
 
 Engagements/Points chart
-*************************
+***********************
 
 Engagements shown on the chart include any tracked action the Contacts made. Some examples might include page hits, Form submissions, Email opens and so on. The engagements line chart displays how active the Contacts of the Company were in the past 6 months. The chart displays also the sum of Points the Contacts received.