kphoen / rusty
Documentation as tests "à la" Rust for PHP
Installs: 3 769
Dependents: 12
Suggesters: 0
Security: 0
Stars: 48
Watchers: 7
Forks: 5
Open Issues: 3
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
This package is auto-updated.
Last update: 2024-10-13 22:56:09 UTC
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.