dox Executable Documentation

Introduction

Start Here

Code and comments

Writing beautiful documentation in code

dox parses code and comments of your test classes and publishes them as executable specification.

Comments, both inside the method body as well as doc comments of methods and classes, are interpreted as markdown and rendered as HTML. So you can create pleasant-to-read documentation (like this one) that still contains executable code which will be presented like this

$some = 1 + 2;
$code = 'Hello';
$more = $code . 'World';

The code is executed when running the test suite so it can (and should) contain assertions

$this->assertEquals(3, $some);
$this->assertEquals('HelloWorld', $more);

For more information see these specifications

or check out the source code of the file containing this documentation.

Do the gherkin

Writing executable specification using an ubiquitous language

I write all of of my executable specification using methods whose names imitate the gherkin syntax. To see examples check out the other specifications of this this project. These methods start with either given, when or then and use underscores as placeholders for arguments to create sentences. For example given_Has_Apples('Bart', 2);.

In order to make these methods more readable, they are parsed specially and presented in a structured way, filling the argument placeholders. The result looks like below. Hover over a step to see its code or check out the source code of this file.

Given 'Bart' has 3 apples
Given 'Lisa' has 2 apples
When 'Bart' gives 'Lisa' 2 apples
Then 'Bart' should have 1 apples
Then 'Lisa' should have 4 apples

Publish your project

How to make the executable documentation of your project browsable with dox

Publish Here

If you would like to publish your project on dox.rtens.org, drop me a line and I'll add it.

Publish yourself

You can also host dox yourself. To do so install dox on your host and the project to the configuration. The best way is to overwrite the configureProjects method in user/UserConfiguration.php.

$project = $this->configuration->addProject('example-name');

The default folder is in user/projects/<projectName> but you can also overwrite it

$this->assertPathEndsWith('user/projects/example-name', $project->getFullProjectFolder());
$project->setFullProjectFolder('/some/absolute/path');
$this->assertPathEndsWith('/some/absolute/path', $project->getFullProjectFolder());

You can either download the files manually into the folder or provide the URL to a git repository to have it downloaded automatically.

$project->setRepositoryUrl('https://github.com/example/project.git');

Automatic Update

If you are using github, you can set up a web hook to automatically update a project on dox every time you push to the repository on github. For more information see the specification.

Test Report

You can send a test report to dox to have the status of each scenario displayed in color: passed, failed, pending, unknown.

For example for dox the commands would be

$ php vendor/phpunit/phpunit/phpunit.php --log-tap build/report.tap
$ curl -X POST --data-binary @build/report.tap http://dox.rtens.org/projects/rtens-dox/reports

For more information see the specification.