kphoen/rusty

Documentation as tests "à la" Rust for PHP

dev-master 2020-07-13 13:41 UTC

Requires

• php: ^7.2
• gregwar/rst: ^1.0
• league/commonmark: ^0.18,>=0.18.3
• nikic/php-parser: ^3.0
• symfony/console: ^4.4|^5.0
• symfony/finder: ^4.4|^5.0
• symfony/process: ^4.4|^5.0

Requires (Dev)

• mikey179/vfsstream: ^1.6
• phpunit/phpunit: ^7.0

MIT

README

The primary way of documenting a Rust project is through annotating the source code. These annotations can be viewed as part of the documentation, but they can also be compiled and executed. They call that "documentation as tests" and their documentation is a goldmine.

Rusty is an attempt at implementing the same idea in the PHP world.

Usage

Rusty is able to extract code samples from both PHP doc-blocks and Markdown files (your documentation for instance).

Running the tests

An executable is provided to analyse the code samples scattered in your documentation and in your doc-blocks:

rusty check -v ./src/

Writing documentation as tests

A code sample usually looks like this:

/**
 * Computes the n-th Fibonacci's number.
 *
 * Examples:
 *
 * ```
 * assert(fibonacci(1) === 1);
 * assert(fibonacci(2) === 1);
 * assert(fibonacci(12) === 144);
 * ```
 *
 * ```should_throw
 * // -1 is invalid, some kind of error is expected
 * fibonacci(-1);
 * ```
 *
 * ```no_execute
 * // it would take too much time to compute, we don't want to wait that long.
 * fibonacci(10000);
 * ```
 */
function fibonacci($n)
{
    if ($n < 0) {
        throw new \DomainException();
    }

    return $n <= 2 ? 1 : fibonacci($n - 1) + fibonacci($n - 2);
}

More examples can be found in the ./examples directory.

Use rusty help check for a list of all the possible options.

Installation

Rusty can either be installed globally:

composer global require kphoen/rusty dev-master

Or locally:

composer require kphoen/rusty dev-master

Both methods will provide the rusty executable.

License

This library is under the MIT license.