Metadata-Version: 2.3
Name: mkdocs-execute-plugin
Version: 0.0.7
Summary: A MkDocs plugin to execute notebooks and embed the results in the documentation.
Project-URL: Homepage, https://gitlab.kwant-project.org/qt/mkdocs-execute-plugin
Project-URL: Issues, https://gitlab.kwant-project.org/qt/mkdocs-execute-plugin/-/issues
Project-URL: Repository, https://gitlab.kwant-project.org/qt/mkdocs-execute-plugin.git
Author-email: MkDocs Execute Plugin Authors <authors@kwant-project.org>
License: BSD 2-Clause License
        
        Copyright (c) 2023, mkdocs-execute-plugin authors
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
License-File: AUTHORS.md
License-File: LICENSE
Classifier: Framework :: MkDocs
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Requires-Dist: ipykernel
Requires-Dist: jupytext
Requires-Dist: markdown
Requires-Dist: mkdocs>=1.4
Requires-Dist: nbconvert
Requires-Dist: traitlets
Description-Content-Type: text/markdown

# 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:

```bash
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`:

```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.

````yml
---
execute: true
---

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

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

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

### Hiding cell input or output

It is possible to hide the input or output of a cell by applying the `hide-input` and `hide-output` tags respectively. It is also possible to hide a cell completely using the `hide-cell`
 tag.

````yml
```python tags=["hide-input"]
print('Hidden input')
```

```python tags=["hide-output"]
print('Hidden output')
```

```python tags=["hide-cell"]
print('Completely hidden')
```
````

## Configuration

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

```yml
# 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: []
      # 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'
      # Markdown template used to render the executed files.
      markdown_template: 'markdown/index.md.j2'
      # You can modify the names of all tags.
      tags:
        # Tag that marks the file as executable.
        execute: 'execute'
        # Tag that hides a cell completely, both the input and output.
        # Note that the cell will still be executed.
        hide_cell: 'hide-cell'
        # Tag that hides the cell input (code).
        hide_input: 'hide-input'
        # Tag that hides the cell output.
        hide_output: 'hide-output'
```

## Supported formats and languages

This plugin uses [jupytext](https://github.com/mwouts/jupytext) to execute and then convert files to markdown. This means all languages and formats supported by jupytext should work.
