Skip to content

Commit

Permalink
Merge pull request #40 from timvink/patch-1
Browse files Browse the repository at this point in the history
Pimp the README.md
  • Loading branch information
greenape authored Sep 15, 2020
2 parents c883d2a + ef467a9 commit 79f31bc
Showing 1 changed file with 11 additions and 2 deletions.
13 changes: 11 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,38 @@
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mknotebooks)
![PyPI](https://img.shields.io/pypi/v/mknotebooks)
![PyPI - Downloads](https://img.shields.io/pypi/dm/mknotebooks)
![GitHub contributors](https://img.shields.io/github/contributors/timvink/mknotebooks)
![PyPI - License](https://img.shields.io/pypi/l/mknotebooks)

# mknotebooks

mknotebooks is a plugin for [MkDocs](https://mkdocs.org), which makes it more convenient to include [Jupyter](https://jupyter.org) notebooks in your project documentation.

## Install

`pip install mknotebooks`
`pip3 install mknotebooks`

## Usage

Simply include any notebooks you want to use in the docs source directory, and add mknotebooks to the plugin section of your `mkdocs.yml` as follows:
Simply include any notebooks you want to use in the docs source directory, and add `mknotebooks` to the plugin section of your `mkdocs.yml` as follows:

```
plugins:
- mknotebooks
```

You can optionally execute the notebooks, by setting `execute: true` in the config, and include a hidden preamble script, to be run before executing any cells using `preamble: "<path/to/your/script>"`. The default cell execution timeout can be overridden by setting `timeout: <timeout>`, where `<timeout>` is an integer number of seconds.

By default, execution will be aborted if any of the cells throws an error, but you can set `allow_errors: true` to continue execution and include the error message in the cell output.

Any static images, plots, etc. will be extracted from the notebook and placed alongside the output HTML.

### Styling

Mknotebooks applies default styling to improve the appearance of notebook input/output cells and pandas dataframes. If these interfere with any other CSS stylesheets that you're using, you can disable these via the following options.

```
# mkdocs.yml
- mknotebooks:
enable_default_jupyter_cell_styling: false
enable_default_pandas_dataframe_styling: false
Expand Down

0 comments on commit 79f31bc

Please sign in to comment.