README

Docbot generates up-to-date and accurate documentation by executing the documentation.

Status

I've hacked this together in 8 hours.

How it works

Essentially:

You provide an article containing a set of delarative blocks.
The blocks are executed output is captured.
The documentation is rendered to a format of your choice (e.g. markdown).

Features

Create and update files.
Execute shell commands and capture the output.
Apply assertions on the result of an executed block.
Add your own extensions to provide custom blocks.
Easily customise the output format to suit your project (e.g. Markdown, Hugo, RsT, HTML, whatever).
Depend on other documents (pre-requisites).
Interact with web pages and capture screenshots (planned).
Lots of other stuff that I haven't done yet.

Usage

Create the following file at docs/example.php:

<?php

use DTL\Docbot\Article\Article;
use DTL\Docbot\Extension\Core\Block\CreateFileBlock;
use DTL\Docbot\Extension\Core\Block\SectionBlock;
use DTL\Docbot\Extension\Core\Block\ShellBlock;
use DTL\Docbot\Extension\Core\Block\TextBlock;

return Article::create('hello_world', 'Hello World', [
    new SectionBlock('Running a shell command', [
        new TextBlock(
            'By default the documentation operates in a clean directory. ' .
            'Create the file `%path%`:',
            context: new CreateFileBlock('hello_world.txt', language: 'text', content: 'Hello World!'),
        ),
        'Now we can execute a shell command and show the contents of that file:',
        new ShellBlock('cat hello_world.txt'),
        'Note that the output from the shell command is shown.',
    ]),
]);

Now let's generate some docs!

$ docbot execute docs

We can view the output... Now we can view the generated document in docs/hello_world.md:

# docs/hello_world.md
Hello World
===========

Running a shell command
-----------------------

By default the documentation operates in a clean directory. Create the file `hello_world.txt`:
```text
Hello World!
```
Now we can execute a shell command and show the contents of that file:
```shell
$ cat hello_world.txt
Hello World!
```
Note that the output from the shell command is shown.

Inception

Oh no! It's a trap 😱! You're in code inception, the source for this file is in ../docs/README.php:

# ../docs/README.php
<?php

use DTL\Docbot\Article\Article;
use DTL\Docbot\Extension\Core\Block\CreateFileBlock;
use DTL\Docbot\Extension\Core\Block\SectionBlock;
use DTL\Docbot\Extension\Core\Block\ShellBlock;
use DTL\Docbot\Extension\Core\Block\ShowFileBlock;
use DTL\Docbot\Extension\Core\Block\TextBlock;

return Article::create('../README', 'DTL Docbot', [
    <<<TEXT
    Docbot **generates** up-to-date and accurate documentation by **executing** the
    documentation.
    TEXT,
    new SectionBlock('Status', [
        'I\'ve hacked this together in 8 hours.',
    ]),
    new SectionBlock('How it works', [
        <<<TEXT
        Essentially:

        - You provide an article containing a set of delarative blocks.
        - The blocks are executed output is captured.
        - The documentation is rendered to a format of your choice (e.g. markdown).
        TEXT,
    ]),
    new SectionBlock('Features', [
        <<<TEXT
        - Create and update files.
        - Execute shell commands and capture the output.
        - Apply assertions on the result of an executed block.
        - Add your own extensions to provide custom blocks.
        - Easily customise the output format to suit your project (e.g. Markdown,
          Hugo, RsT, HTML, whatever).
        - Depend on other documents (pre-requisites).
        - Interact with web pages and capture screenshots (_planned_).
        - Lots of other stuff that I haven\'t done yet.
        TEXT
    ]),
    new SectionBlock('Usage', [
        new TextBlock(
            'Create the following file at `%path%`:',
            context: new CreateFileBlock(path: 'docs/example.php', language: 'php', content: <<<'PHP'
                <?php

                use DTL\Docbot\Article\Article;
                use DTL\Docbot\Extension\Core\Block\CreateFileBlock;
                use DTL\Docbot\Extension\Core\Block\SectionBlock;
                use DTL\Docbot\Extension\Core\Block\ShellBlock;
                use DTL\Docbot\Extension\Core\Block\TextBlock;

                return Article::create('hello_world', 'Hello World', [
                    new SectionBlock('Running a shell command', [
                        new TextBlock(
                            'By default the documentation operates in a clean directory. ' .
                            'Create the file `%path%`:',
                            context: new CreateFileBlock('hello_world.txt', language: 'text', content: 'Hello World!'),
                        ),
                        'Now we can execute a shell command and show the contents of that file:',
                        new ShellBlock('cat hello_world.txt'),
                        'Note that the output from the shell command is shown.',
                    ]),
                ]);
                PHP,
            ),
        ),
        'Now let\'s generate some docs!',
        new ShellBlock('docbot execute docs', env: [
            'PATH' => getenv('PATH', true).':'.__DIR__.'/../bin',
        ]),
        'We can view the output...',
        new TextBlock(
            'Now we can view the generated document in `%path%`:',
            context: new ShowFileBlock('docs/hello_world.md', 'text'),
        ),
    ]),
    new SectionBlock('Inception', [
        new TextBlock(
            'Oh no! It\'s a trap 😱! You\'re in code inception, the source for this file is in `%path%`:',
            context: new ShowFileBlock('../docs/README.php', 'php'),
        ),
    ]),
]);

dantleech / docbot

Maintainers