Improving atoum's documentation using Rusty
@agallou - 21 Nov 2016
atoum’s documentation contains a lot of PHP examples. Sometimes they don’t work because of syntax errors.
In the example below, a semicolon is missing at the end of the line. So, a user pasting it won’t have a working example.
Let’s look at how we removed errors like this using Rusty.
Usage in atoum
Adding support for RST
When we started using it, Rusty supported markdown, but not RST. Fortunately, Rusty’s architecture enables you to add new formats. So we made a pull Request to add support of RST (based on the gregwar/rst library).
Fixing linting errors
We launch Rusty like this:
./vendor/bin/rusty check --no-execute source/ -v
This command launches Rusty and only lints the content of the files in the “source” folder. Code blocks are not executed.
The result of this command is the following output:
From this ouput, we can see that Rusty;
- will search for supported file extensions (php, markdown, and RST);
- will parse those files and search for php code in markdown and RST documentation, or in PHPDoc;
- if php code is found, it will lint it and check that the syntax is correct
- where it finds syntax errors, the offending php code will be displayed alongside the error message.
As a first step in improving atoum’s documentation, Rusty helped us detect and fix numerous mistakes (you can can see them in this pull Request).
Fixing mistakes is good. Avoiding them reappearing is even better.
To prevent such errors we’ve added a travis configuration to our documentation repository in order to alert (via the pull request status) the documentation writers when such a mistake occurs.
You can see an example of an implementation of Rusty on travis in this pull Request.
Documentation is a major point in the adoption of an open-source project.
Good quality, working examples can make all the difference in the choice of a library. Using Rusty helps you improve the experience your users have of your project’s documentation.