mamazu/documentation-validator

A validator tool that can validate markdown documentation

1.6.0 2022-02-05 17:20 UTC

Requires

• php: ^7.4|^8
• ext-dom: *
• ext-json: *
• ext-libxml: *
• mamazu/rst: ^2.0
• nikic/php-parser: ^4.2
• symfony/filesystem: ^4|^5.3
• symfony/yaml: ^4|^5

Requires (Dev)

• mikey179/vfsstream: ^1.6
• phpspec/phpspec: ^5.1|^6.0
• phpstan/phpstan: ^0.12.78
• phpstan/phpstan-strict-rules: ^0.12.9
• phpstan/phpstan-webmozart-assert: ^0.12.12
• symplify/easy-coding-standard: ^10.0

MIT

• mamazu

README

Every project needs documentation which is usually accompanied by code snippets that show how a component is integrated. The problem is how does the project ensure that this code runs and that the code is up to date? Then this is your tool.

Installation

This is a dev only package. Installing it without dev dependencies will cause problems.

composer require --dev mamazu/documentation-validator

vendor/bin/doc-parser <files to check>

How to use it

bin/phpdoc-parser <path> [-i extensionscript.php]

path			Path containing the documentation
-i script.php	Configuration script of the application

Example:
bin/doc-parser docs					# Validate with default configuration
bin/doc-parser docs -i config.php	# Validate with custom configuration

The configuration of the extension is loaded before the application starts. For a template checkout the tests/extensions/delete.php file. An example for adding more validators is given in the tests/extensions/add_phpstan.php file which also adds the validation rules of PHPstan.

Supported parsing formats

Here is the full list of parsers that this library supports:

• IgnoredFileParser (this allows ignoring certain extensions like pdf files)
• Markdown (only supporting block comments for now)
• RstParser
• LatexParser (only supporting the lstlisting package)

Validators

• CompositeValidator: Validates all of its children passed into the constructor
• Bash:
  • BashValidator: Validates bash or sh files with the build in spellchecker
• PHP:
  • ClassExistenceValidator: Validates if the classes referenced in the use statement exist
  • PhpStanValidator (optional): Validates the code with PHPstan
  • EnvValidator: Validate the contents of the .env files
• XML:
  • XMLValidator: Checks if the document contains valid XML
• YAML / YML:
  • YamlValidator: Checks if the document contains valid Yaml
• JSON:
  • JsonValidator: Default PHP JSON parsing without line numbers of errors