mamazu / documentation-validator
A validator tool that can validate markdown documentation
Installs: 7 131
Dependents: 3
Suggesters: 0
Security: 0
Stars: 9
Watchers: 6
Forks: 2
Open Issues: 1
Type:project
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
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