mkdocs-execute-plugin 0.0.5

A MkDocs plugin to execute notebooks and embed the results in the documentation.

MkDocs Execute Plugin

Plugin for MkDocs that executes documentation files using jupytext and embeds the output in your documentation.

Installation

Start by install the plugin using pip:

pip install mkdocs-execute-plugin

Basic usage

Configuring mkdocs

After installing it, you can enable the plugin by adding it to the plugin section of your mkdocs.yml:

plugins:
  - execute

Adding executable files

By default, this plugin will execute all code blocks inside markdown files if the file has the execute tag. An example markdown file can be found below.

---
execute: true
---

```python
print('Hello world!')
```

On top of that, the plugin will also execute all python (.py) files by default.

print('Hello world!')

Configuration

All configuration options can be found below. The given values are the defaults.

# Default configuration
plugins:
  - execute:
      # Specify which files to include for execution. Should be a list of .gitignore style glob patterns.
      # Note that only files with the execute tag set to true will be executed. To override, see `execute_without_tag`.
      include: 
        - '*.py'
        - '*.md'
      # Specify which glob patterns to exclude for execution. Same format as `include`.
      exclude: []
      # The name of the tag that marks the file as executable.
      execute_tag_name: 'execute'
      # Specify which files should still be executed if the execute tag is missing. Same format as `include`.
      # If the execute is set to false for a file matching this pattern, it will NOT be executed.
      execute_without_tag:
        - '*.py'

Supported formats and languages

This plugin uses jupytext to execute and then convert files to markdown. This means all languages and formats supported by jupytext should work.