markdown-exec/docs/gallery.md

hide

hide
navigation

Gallery

Welcome to our gallery of examples!

Diagrams, charts, graphs, plots

with Diagrams

Diagram as Code for prototyping cloud system architectures.

```python exec="true" html="true"
--8<-- "gallery/diagrams.py"
```

with D2

A modern diagram scripting language that turns text to diagrams.

```python exec="true" html="true"
--8<-- "gallery/d2.py"
```

with Matplotlib

Matplotlib is a comprehensive library for creating static, animated, and interactive visualizations in Python.

```python exec="1" html="1"
--8<-- "gallery/matplotlib.py"
```

with pipdeptree

A command line utility to display dependency tree of the installed Python packages.

We call pipdeptree with its --mermaid option to generate a Mermaid diagram.

```bash exec="1" result="mermaid"
# Change the direction of the graph from top-down to left-right,
# and remove local version identifiers from our own package.
pipdeptree -p markdown-exec --mermaid 2>/dev/null |
    sed -E 's/\.dev.+"\]$/"]/;s/\+d.*"\]$/"]/'
```

Another example with more dependencies:

```bash exec="1" result="mermaid"
pipdeptree -p mkdocstrings-python --mermaid 2>/dev/null |
    sed 's/flowchart TD/flowchart LR/'
```

with Plotly

The interactive graphing library for Python ✨

```python exec="true" html="true"
--8<-- "gallery/plotly.py"
```

with pydeps

Python Module Dependency graphs.

pydeps uses Graphviz under the hood to generate graphs. In this example we add links to the code reference in related nodes. Try clicking on the markdown_exec nodes!

```python exec="true" html="true"
--8<-- "gallery/pydeps.py"
```

Code snippets

with Rich

Rich is a Python library for rich text and beautiful formatting in the terminal.

```python exec="true" html="true"
--8<-- "gallery/rich.py"
```

with PyTermGUI

Python TUI framework with mouse support, modular widget system, customizable and rapid terminal markup language and more!

```python exec="true" html="true"
--8<-- "gallery/pytermgui.py"
```

TIP: There's a PyTermGUI-dedicated MkDocs plugin that allows to generate SVGs on-the-fly: Termage. It is implemented using regular expressions in the on_markdown event of MkDocs, so is probably less robust than our actual SuperFence implementation here, but also allows for less verbose source to generate the SVG snippets.

Console output

If you installed Markdown Exec with the ansi extra (pip install markdown-exec[ansi]), the ANSI colors in the output of shell commands will be translated to HTML/CSS, allowing to render them naturally in your documentation pages. For this to happen, use the result="ansi" option.

```bash exec="true" result="ansi"
--8<-- "gallery/ansi.sh"
```

with Rich

Rich is a Python library for rich text and beautiful formatting in the terminal.

```python exec="true" html="true"
--8<-- "gallery/rich_terminal.py"
```

SVG drawings

with Chalk

A declarative drawing API in Python.

```python exec="true" html="true"
--8<-- "gallery/chalk.py"
```

with Drawsvg 2

Programmatically generate SVG (vector) images, animations, and interactive Jupyter widgets.

```python exec="true" html="true"
--8<-- "gallery/drawsvg.py"
```

with Hyperbolic

A Python 3 library for constructing and drawing hyperbolic geometry.

```python exec="true" html="true"
--8<-- "gallery/hyperbolic.py"
```

QRCodes

with qrcode

Python QR Code image generator.

```python exec="true" html="true"
--8<-- "gallery/qrcode.py"
```

TUI screenshots

with Textual

Textual is a Rapid Application Development framework for Python, built by Textualize.io.

```python exec="1" html="true"
--8<-- "gallery/textual.py"
```

File-trees

This example displays a file-tree of the current project, in which you can descend thanks to Material for MkDocs' code annotations. It uses a recursive Python function which accept a code block session name as parameter 🤯:

```python exec="1" session="filetree"
--8<-- "gallery/expandable_filetree.py"
```

```python exec="1" session="filetree"
exptree(".", "filetree")
```

Python CLI documentation

with argparse (code block)

If you know a project is using argparse to build its command line interface, and if it exposes its parser, then you can get the help message directly from the parser.

```python exec="true"
--8<-- "gallery/argparse_format.py"
```

with argparse (Markdown)

In this example, we inspect the argparse parser to build better-looking Markdown/HTML contents. We simply use the description and iterate on options, but more complex stuff is possible of course.

```python exec="true" updatetoc="no"
--8<-- "gallery/argparse.py"
```

with runpy

This example uses Python's runpy module to run another Python module. This other module's output is captured by temporarily patching sys.stdout with a text buffer.

```python exec="true"
--8<-- "gallery/runpy.py"
```