autoreadme

Generate READMEs with collapsable* code and corresponding output from Python.

Installation

from package

# Set up a virtualenv. 
python3 -m venv venv
source venv/bin/activate

# Install from PyPI
pip install autoreadme

from source

git clone https://github.com/davips/autoreadme
cd autoreadme

Example

A typical README-edit.md file would be:

# Uses
We can cook using the following Python code:
<<cook>>

However, we can also clean:
<<clean>>

The example file (given in this repo as examples/README-edit.md) depends on two scripts. Each script should have a # ... line where the output until that moment is expected to appear:

examples/cook.py:

# Cooking
x = 2 * 8
print("This script prints something:", x)
# ...

examples/clean.py:

# Cleaning
y = 34 % 5
print("this script prints another thing.", y)
# ...

Running...

autoreadme -i examples/README-edit.md -s examples/ -o examples/README.md examples/README-edit.md

...will result in the following markdown:

# Uses

We can cook using the following Python code:

Cooking

Details

x = 2 * 8
print("This script prints something:", x)

This script prints something: 16

However, we can also clean:

Cleaning

Details

y = 34 % 5
print("this script prints another thing.", y)

this script prints another thing. 4