README

🌹 XULIETA

Xulieta is a light php binary that lint documentation snippets.

Xulieta is a light php binary that find code snippets thought out documentation files — as for example *.md, *.markdown and *.rst — and lint the pieces of code, so you can find basic documentation errors.

NOTE: For now we just lint PHP code.

Installation

composer require codelicia/xulieta

Checking for errors

In order to lint the basics of documentation structure, one just needs to provide a path for a directory or file to be linted.

./vendor/bin/xulieta check:error <directory>

Integration with GitHub Actions

We provide out of the box an output format that you can use to have automatic feedback from GitHub CI. That is done by specifying the checkstyle output and passing it to some external binary that does the commenting.

We recommend the usage of cs2pr.

./vendor/bin/xulieta check:error <directory> --output=checkstyle | cs2pr

Commenting example

$Codelicia\Xulieta$

Advanced Configuration

Xulieta tries to find a .xulieta.xml file in the root of your project with the following configuration format:

<?xml version="1.0" encoding="UTF-8" ?>
<xulieta xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="./vendor/codelicia/xulieta/xulieta.xsd">

    <parser>Codelicia\Xulieta\Parser\MarkdownParser</parser>
    <parser>Codelicia\Xulieta\Parser\RstParser</parser>

    <validator>Codelicia\Xulieta\Validator\PhpValidator</validator>

    <outputFormatters>Codelicia\Xulieta\Output\Checkstyle</outputFormatters>

    <exclude>vendor</exclude>
    <exclude>node_modules</exclude>
</xulieta>

parser: listing of all parses to handle file formats based in the extention name
validator: performs verification on a given code block
outputFormatters: personalized output formatter
exclude: excluded directory or files

Command name

For historic reasons and the sake of the Brazilian MEME we keep the original command xulieta check:erromeu.

Plugins

Xulieta will automatically scan dependencies to see if there is any package that is providing default configurations.

If you want your plugin to take advantage of that functionality, we expect you to provide some information on your composer.json file, ie:

{
  "extra": {
    "xulieta": {
      "parser": ["Malukenho\\QuoPrimumTempore\\JsonParser"],
      "validator": ["Malukenho\\QuoPrimumTempore\\JsonValidator"]
    }
  }
}

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

codelicia / xulieta

Maintainers

Details