https://github.com/ottomatica/docable
:gear::ledger: CI for documentation. Testing if documentation is runable.
https://github.com/ottomatica/docable
ci documentation testing tutorial
Last synced: 7 months ago
JSON representation
:gear::ledger: CI for documentation. Testing if documentation is runable.
- Host: GitHub
- URL: https://github.com/ottomatica/docable
- Owner: ottomatica
- License: apache-2.0
- Created: 2019-05-22T14:12:24.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T03:46:51.000Z (almost 3 years ago)
- Last Synced: 2025-04-07T15:23:13.977Z (10 months ago)
- Topics: ci, documentation, testing, tutorial
- Language: JavaScript
- Homepage:
- Size: 1.93 MB
- Stars: 11
- Watchers: 3
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# docable
_CI for documentation_: Testing if documentation is runable.
Suppose you wanted to test the following tutorial (inspired from [benmoral](https://medium.com/@benmorel/creating-a-linux-service-with-systemd-611b5c8b91d6).)
## Example Tutorial
Let’s create a small server using PHP. I can see your eyebrows rising, but it works surprisingly well. We’ll listen to UDP port 10000, and return any message received with a ROT13 transformation:
```php
server.php
- selectAndServe: "start it:"
- selectAndExpect: "another terminal:"
```
The stepfile using a "select-assert" pattern for testing documentation. That is, we first find an instruction step in the tutorial using a lightweight selector, then, we transform the step into an action we can perform within a "headless infrastructure" (such as a vm), and finally we assert it's behavior is correct.
The result looks something like this:
Turns out that our tutorial breaks if using a different version of netcat, which does not support the `-q 1` option. Oops!
After fixing the issue by changing to using "-w 1" (terminated after timeout instead of time since no STDIN input). Running `docable test`, we verify have fixed the tutorial:
## Installing docable
```
$ git clone https://github.com/ottomatica/docable
$ npm install
$ npm link
```
Using `slim` provider requires installing [slim](https://github.com/ottomatica/slim). You can also switch the stepfile to use a local provider under `setup:`.