DocExec

About

doc-exec is a tool that can:

• parse documentation files,
• extract code blocks,
• execute them,
• and update the documentation with the execution result.

It's similar to executable documentation tools like Jupyter notebooks but for general documentation formats.

Example

With the doc-exec cli

doc-exec \
  --doc-path /path/to/the/doc/directory \
  --file-path /path/to/the/file/directory \
  run \
  relative/glob/path/to/the/doc

See the DocExecutorCli Class for all options

Embedded as a library

// The documentation file to execute
final Path path = Paths.get("./src/test/resources/docTest/fileTest.txt");

// Execution
List<DocExecutorResult> docTestRuns = DocExecutor
  .create("run-name")
  // where to find the files to inject
  .setBaseFileDirectory(Paths.get("./src/test/resources"))
  .setShellCommandExecuteViaMainClass("cat", CommandCat.class)
  .build()      
  .run(path);

See the DocExecutor Class for all options

Doc-Exec Execution

It will:

• scan for unit node
• capture the file, code and console node
• replace the file content if present
• execute the code block if present and replace the console block (if present) with the result

Unit Node Syntax

A unit may have:

• one or more file block (to replace the content of a file, generally used in the code)
• zero or one code block (the code to execute)
• zero or one console block (to get the content of the code execution)

<unit envHOME="Whatever">
    <file lang path/to/File>
    </file>
    <code bash>
       echo $HOME
    </code>
    <console>
        Whatever
    </console>
</unit>

Lang

Java

Java

Shell Command (Dos, Bash)

Shell

Features

Inject result of code execution

It will replace the content of a console block with the result of a code execution.

File replacement

It will replace the content of the file inside the file block

<unit>
    <file lang path/to/File>
    </file>
</unit>

The paths are relative to the base file directory

Installation

Brew (Linux, Windows WSL, macOS)

For Linux/Windows WSL and macOS, with brew

brew install combostrap/tap/doc-exec

Docker (Linux, Windows, macOS)

With docker releases

docker run \
  --rm \
  -v $(pwd):/workspace \
  ghcr.io/combostrap/doc-exec-alpine:latest \
  doc-exec --version

Winget (Windows)

winget install --id combostrap.doc-exec

Note that you may get a Windows protected your PC. To continue, click on the More info link and on the button Run anyway