oskarstark/doctor-rst

1.62.3 2024-08-28 12:09 UTC

Requires

• php: ^8.3
• ext-ctype: *
• ext-iconv: *
• ext-mbstring: *
• composer/semver: ^3.4.2
• ondram/ci-detector: ^4.2.0
• symfony/config: ^7.1.1
• symfony/console: ^7.1.3
• symfony/dependency-injection: ^7.1.3
• symfony/finder: ^7.1.3
• symfony/options-resolver: ^7.1.1
• symfony/service-contracts: ^3.5.0
• symfony/string: ^7.1.3
• symfony/yaml: ^7.1.1
• webmozart/assert: ^1.11

Requires (Dev)

• ergebnis/composer-normalize: ^2.43.0
• ergebnis/php-cs-fixer-config: ^6.34
• ergebnis/test-util: ^1.6
• icanhazstring/composer-unused: ^0.8.11
• mikey179/vfsstream: ^1.6.11
• phpstan/extension-installer: ^1.4.1
• phpstan/phpstan: ^1.11.10
• phpstan/phpstan-phpunit: ^1.4.0
• phpstan/phpstan-webmozart-assert: ^1.2.9
• phpunit/phpunit: ^10.5.27
• rector/rector: ^1.2.2
• symfony/var-dumper: ^7.1.3

Replaces

• paragonie/random_compat: ^2.0
• symfony/polyfill-ctype: *
• symfony/polyfill-iconv: *
• symfony/polyfill-php56: *
• symfony/polyfill-php70: *
• symfony/polyfill-php71: *
• symfony/polyfill-php72: *
• symfony/polyfill-php73: *
• symfony/polyfill-php74: *
• symfony/polyfill-php80: *
• symfony/polyfill-php81: *
• symfony/polyfill-php82: *
• symfony/polyfill-php83: *

MIT

README

Lint your documentation against given rules.

Available rules

You can find the available rules here.

Usage

You can use it as a Github Action like this:

# .github/workflows/lint.yaml
name: Lint

on:
    push:
    pull_request:

jobs:
    doctor-rst:
        name: DOCtor-RST
        runs-on: ubuntu-latest
        steps:
            - name: "Checkout code"
              uses: actions/checkout@v4

            - name: DOCtor-RST
              uses: docker://oskarstark/doctor-rst
              with:
                  args: --short --error-format=github

If your *.rst files are not located in root:

              uses: docker://oskarstark/doctor-rst
              with:
                  args: --short --error-format=github
+              env:
+                  DOCS_DIR: 'docs/'

Error Formatter

• detect (default) If running inside GithubActions CI environment, github is used, otherwise console.

• github Used to annotate your pull requests.

• console Used to generate a human readable output.

To force the usage of a specific formatter, use the --error-format option.

Use Caching to Speedup your GithubActions builds

        steps:
            - name: "Checkout"
              uses: actions/checkout@v4

+            - 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: doctor-rst-${{ runner.os }}-${{ steps.extract_base_branch.outputs.branch }}
+                  restore-keys: |
+                      doctor-rst-${{ runner.os }}-
+                      doctor-rst-   
+
            - name: "Run DOCtor-RST"
              uses: docker://oskarstark/doctor-rst
              with:
-                 args: --short --error-format=github
+                 args: --short --error-format=github --cache-file=/github/workspace/.cache/doctor-rst.cache

Docker

A Docker-Image is built automatically and located here: https://cloud.docker.com/u/oskarstark/repository/docker/oskarstark/doctor-rst

You can run it in any given directory like this:

docker run --rm -it -e DOCS_DIR='/docs' -v ${PWD}:/docs oskarstark/doctor-rst:latest

Local usage

bin/doctor-rst analyze dummy --group=@Symfony

or

bin/doctor-rst analyze dummy --group=@Sonata

Todos

• Allow to register custom Rules
• Move logic from Command to Services