| Name | snipinator JSON |
| Version |
3.1.2
JSON |
| download |
| home_page | None |
| Summary | Python code snippets for markdown files, e.g READMEs, from actual (testable) code. |
| upload_time | 2024-08-09 06:08:45 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 Azriel Fasten. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
github
testing
markdown
readme
snippets
documentation
jinja2
templates
preprocessor
documentation-tool
include
readme-template
readme-md
dynamic-documentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
WARNING: This file is auto-generated by snipinator. Do not edit directly.
SOURCE: `.github/README.md.jinja2`.
-->
<!--
-->
# <div align="center">[![Snipinator][1]][2]</div>
<div align="center">
<!-- Icons from https://lucide.dev/icons/users -->
<!-- Icons from https://lucide.dev/icons/laptop-minimal -->
![**Audience:** Developers][3] ![**Platform:** Linux][4]
</div>
<p align="center">
<strong>
<a href="https://github.com/realazthat/snipinator">🏠Home</a>
•
<a href="#-features">🎇Features</a>
•
<a href="#-install">🔨Install</a>
•
<a href="#-usage">🚜Usage</a>
•
<a href="#-command-line-options">💻CLI</a>
•
<a href="#-examples">💡Examples</a>
</strong>
</p>
<p align="center">
<strong>
<a href="#-jinja2-api">🤖Jinja2 API</a>
•
<a href="#-requirements">✅Requirements</a>
•
<a href="#-docker-image">🐳Docker</a>
•
<a href="#-gotchas-and-limitations">🚸Gotchas</a>
</strong>
</p>
<div align="center">
![Top language][5] [![GitHub License][6]][7] [![PyPI - Version][8]][9]
[![Python Version][10]][9]
**CLI to embed (testable) snippets from your codebase into your README**
</div>
---
<div align="center">
| | Status | Stable | Unstable | |
| ----------------- | --------------------------- | ------------------------- | ------------------------- | ------------------------ |
| **[Master][11]** | [![Build and Test][12]][13] | [![since tagged][14]][15] | | [![last commit][16]][17] |
| **[Develop][18]** | [![Build and Test][19]][13] | [![since tagged][20]][21] | [![since tagged][22]][23] | [![last commit][24]][25] |
</div>
<img alt="Demo" src="https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/demo.gif" width="100%"/>
## ❔ What
What it does: **Snipinator** lets you take a `EXAMPLE.md` template
and include snippets from your (working and tested) codebase.
Turn this ([./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2)):
<!---->
```md
# A README
Here is a code snippet:
<!--{{ pysnippet(path='snipinator/examples/code.py', symbol='MyClass', backtickify='py', decomentify='nl') }}-->
Note that `code.py` has a test:
{{path('./snipinator/examples/code_test.py', link='md')}}.
```
<!---->
Into this ([./snipinator/examples/SIMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.generated.md)):
<!---->
````md
<!--
WARNING: This file is auto-generated by snipinator. Do not edit directly.
SOURCE: `snipinator/examples/SIMPLE.md.jinja2`.
-->
# A README
Here is a code snippet:
<!---->
```py
class MyClass:
"""This is a global class"""
def __init__(self, name):
self.name = name
def MyClassMethod(self):
"""This is a method of MyClass"""
print(self.name)
```
<!---->
Note that `code.py` has a test:
[./snipinator/examples/code_test.py](./snipinator/examples/code_test.py).
````
<!---->
## 🎇 Features
- 📦✅🪄 Supports anything **[Jinja2](https://github.com/pallets/jinja)**
supports.
- 🥇🐍📜 First-class support for **python** source code.
- Can include python function signatures, docstrings, entire function source
code, classes.
- ✂🌐🗂️ Snip from **any source code language**.
- Put delimiter markers into the code (e.g `# START_SNIPPET`,
`# END_TEMPLATE`), and use [snippet()](#snippet).
- 🥇🔖📜 First-class support for **Markdown** templates (with `backtickify`,
`decomentify`).
- 📦🐚🖨️ Can include **[shell](#shell) output**.
- Supports ANSI colors :heart: :green_heart: :blue_heart: with SVG output
:camera:.
- ⚙️🔗🗃️ More robust **references/links** to local files using [path()](#path).
- 🐳🌊🖥️ Docker Image (See [README: Docker Image](#-docker-image)).
## 🔨 Install
```bash
# Install from pypi (https://pypi.org/project/snipinator/)
pip install snipinator
# Install from git (https://github.com/realazthat/snipinator)
pip install git+https://github.com/realazthat/snipinator.git@v3.1.2
```
## 🚜 Usage
Example template README:
([./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2)):
<!---->
```md
# A README
Here is a code snippet:
<!--{{ pysnippet(path='snipinator/examples/code.py', symbol='MyClass', backtickify='py', decomentify='nl') }}-->
Note that `code.py` has a test:
{{path('./snipinator/examples/code_test.py', link='md')}}.
```
<!---->
Generating the README:
<!---->
````bash
$ python -m snipinator.cli -t snipinator/examples/SIMPLE.md.jinja2
<!--
WARNING: This file is auto-generated by snipinator. Do not edit directly.
SOURCE: `snipinator/examples/SIMPLE.md.jinja2`.
-->
# A README
Here is a code snippet:
<!---->
```py
class MyClass:
"""This is a global class"""
def __init__(self, name):
self.name = name
def MyClassMethod(self):
"""This is a method of MyClass"""
print(self.name)
```
<!---->
Note that `code.py` has a test:
[./snipinator/examples/code_test.py](./snipinator/examples/code_test.py).
````
<!---->
Fuller example:
<!---->
<img alt="Output of `bash ./snipinator/examples/simple_example.sh`" src="https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/README.example.generated.svg"/>
<!-- -->
## 💻 Command Line Options
<!---->
<img alt="Output of `python -m snipinator.cli --help`" src="https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/README.help.generated.svg"/>
<!-- -->
## 💡 Examples
- Snipinator's own `README`:
- Template: [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
- Generated: [./README.md](https://github.com/realazthat/snipinator/blob/v3.1.2/README.md).
- Generation script: [./scripts/generate-readme.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/scripts/generate-readme.sh).
- Example:
- Template: [./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2).
- Generated: [./snipinator/examples/SIMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.generated.md).
- Generation script:
[./snipinator/examples/simple_example.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/simple_example.sh).
- Long example of many features:
- Template:
[./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).
- Generated:
[./snipinator/examples/LONG-EXAMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.generated.md).
- Generation script:
[./snipinator/examples/long_example.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/long_example.sh).
- Projects using Snipinator:
- [realazthat/snipinator][26]
- Template: [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
- Generated: [snipinator/README.md][27].
- Generation script: [snipinator/scripts/generate-readme.sh#L20][28].
- [realazthat/mdremotifier][29].
- Template: [mdremotifier/README.md.jinja2][30].
- Generated: [mdremotifier/README.md][31].
- Generation script: [mdremotifier/generate-readme.sh#L20][32].
- [realazthat/changeguard][33].
- Template: [changeguard/README.md.jinja2][34].
- Generated: [changeguard/README.md][35].
- Generation script: [changeguard/generate-readme.sh#L20][36].
- [realazthat/excalidraw-brute-export-cli][37],
- Template: [excalidraw-brute-export-cli/README.md.jinja2][38].
- Generated: [excalidraw-brute-export-cli/README.md][39].
- Generation script:
[excalidraw-brute-export-cli/generate-readme.sh#L65][40].
- [realazthat/comfy-catapult][41].
- Template: [comfy-catapult/README.md.jinja2][42].
- Generated: [comfy-catapult/README.md][43].
- Generation script: [comfy-catapult/generate-readme.sh#L17][44].
- [realazthat/comfylowda][45].
- Template: [comfylowda/README.md.jinja2][46].
- Generated: [comfylowda/README.md][47].
- Generation script: [comfylowda/generate-readme.sh#L17][48].
## 🤖 Jinja2 API
The regular Jinja2 v3 template syntax is supported. For more information, see
[Template Designer Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/).
Additional (Jinja2) functions made available:
### 🐍✂ pysnippet
Used several times in
[./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).
Documentation:
<!---->
```py
def pysnippet(path: str,
symbol: Optional[str],
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
_ctx: _Context) -> Union[str, markupsafe.Markup]:
"""Return a python snippet, allowing you to specify a class or function.
Args:
path (str): The path to the file.
symbol (Optional[str]): The symbol to extract. If None, the entire file is
returned. Defaults to None.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (Union[bool, Literal['nl']], optional): Assuming that you will
be using HTML comments around this call, setting this to true will add
correspondingcomments to uncomment the output. This allows you to have
the Jinja2 call unmolested by markdown formatters, because they will be
inside of a comment section. "nl" adds additional newlines after the
newline delimiters. Defaults to False.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
Union[str, markupsafe.Markup]: The snippet.
"""
```
<!---->
### 🐍📖 pysignature
Used several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
Documentation:
<!---->
```py
def pysignature(path: str,
symbol: str,
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
_ctx: _Context) -> str:
"""Return the signature of a class or function in a python file.
Returns the {class,function} signature and the docstring.
Args:
path (str): The path to the file.
symbol (str): The symbol to extract.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (Union[bool, Literal['nl']], optional): Assuming that you will
be using HTML comments around this call, setting this to true will add
correspondingcomments to uncomment the output. This allows you to have
the Jinja2 call unmolested by markdown formatters, because they will be
inside of a comment section. "nl" adds additional newlines after the
newline delimiters. Defaults to False.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
str: The signature and docstring.
"""
```
<!---->
### ✂ rawsnippet
Used several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
Documentation:
<!---->
```py
def rawsnippet(path: str,
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
_ctx: _Context) -> Union[str, markupsafe.Markup]:
"""Return an entire file as a snippet.
Args:
path (str): The path to the file.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (Union[bool, Literal['nl']], optional): Assuming that you will
be using HTML comments around this call, setting this to true will add
correspondingcomments to uncomment the output. This allows you to have
the Jinja2 call unmolested by markdown formatters, because they will be
inside of a comment section. "nl" adds additional newlines after the
newline delimiters. Defaults to False.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
Union[str, markupsafe.Markup]: The snippet.
"""
```
<!---->
### ✂ snippet
Example in [./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).
Documentation:
<!---->
```py
def snippet(path: str,
start: str,
end: str,
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
regex: Union[bool, str] = False,
_ctx: _Context) -> Union[str, markupsafe.Markup]:
"""Returns a _delimited_ snippet from a file.
Does not return the delimiters themselves.
Args:
path (str): The path to the file.
start (str): A string that indicates the start of the snippet.
end (str): A string that indicates the end of the snippet.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (Union[bool, Literal['nl']], optional): Assuming that you will
be using HTML comments around this call, setting this to true will add
correspondingcomments to uncomment the output. This allows you to have
the Jinja2 call unmolested by markdown formatters, because they will be
inside of a comment section. "nl" adds additional newlines after the
newline delimiters. Defaults to False.
regex (Union[bool, str], optional): If True, `start` and `end` will be
treated as regular expressions. Optionally, can pass in python regex
flags separated by `|` characters, e.g "IGNORECASE|MULTILINE". Defaults
to False.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
Union[str, markupsafe.Markup]: The snippet.
"""
```
<!---->
### 🐚 shell
Used several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
Documentation:
<!---->
```py
def shell(args: str,
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
rich: Union[Literal['svg'], Literal['img+b64+svg'], Literal['raw'],
str] = 'raw',
rich_alt: Optional[str] = None,
rich_bg_color: Optional[str] = None,
rich_term: Optional[str] = None,
rich_rows: int = 24,
rich_cols: int = 80,
include_args: bool = True,
start: Optional[str] = None,
end: Optional[str] = None,
regex: Union[bool, str] = False,
_ctx: _Context) -> Union[str, markupsafe.Markup]:
"""Run a shell command and return the output.
Use at your own risk, this can potentially introduce security vulnerabilities.
Only use if you know what you are doing. Ensure that no untrusted input can
be injected into the `args` parameter, or, into anything the command might
access. If an adversary can control the `args` parameter, they can execute
arbitrary commands on your system.
Note: On persistent output colors:
* I found that the environment variables TERM, COLORTERM and FORCE_COLOR,
CLI_WIDTH, COLUMNS also influence the outputs for some applications.
* Also various library versions used in various programs, e.g colorama,
rich-argparse, Pygments might influence the output.
* I had to pin all my python packages, and explicitly set TERM, COLORTERM and
FORCE_COLOR, CLI_WIDTH, COLUMNS to get the output to be consistent across
two different systems, both using Ubuntu, for a single program.
Args:
args (str): The command to run.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (bool, optional): Assuming that you will be using HTML
comments around this call, setting this to true will add corresponding
uncomments to uncomment the output. This allows you to have the Jinja2
call unmolested by markdown formatters, because they will be inside of
a comment section. Defaults to False.
rich (Union[Literal['svg'], Literal['img+b64+svg'], Literal['raw'], str],
optional):
Optionally outputs colored terminal output as an image.
* If `rich` is a relative file path that ends with ".svg", the svg will
be saved to that location and an img tag will be emitted. The path
will be relative to the template file, which is specified on the
command line. If the template is from stdin, the path will be relative
to the current working directory (cwd) which is also specified on the
command line.
* If 'svg' a raw svg tag will be dumped into the markdown with the
colored terminal output. Note that your markdown renderer may not
support this.
* If 'img+svg' a base64 encoded image will be dumped into the markdown
with the colored terminal output.
* If 'raw' the raw (uncolored) terminal output will be dumped into the
markdown directly.
* Defaults to 'raw.
rich_alt (str, optional): The alt text for the img tag. Defaults
to None.
rich_bg_color (str, optional): The background color for the
terminal output. Valid colors include anything valid for SVG colors. See
<https://developer.mozilla.org/en-US/docs/Web/CSS/color>. Defaults to
None (fully transparent).
rich_term: (str, optional): Sets the TERM env var. Defaults to
None, which uses whatever the env vars already have.
rich_rows (int, optional): The number of rows to use for the terminal
output. Doesn't seem to have much effect. Defaults to 24.
rich_cols (int, optional): The number of columns to use for the terminal
output. Defaults to 80.
include_args (bool, optional): Should include the command that was run in
the output? Defaults to True.
start (str, optional): If specified, will return only the text after this
delimiter. Defaults to None.
end (str, optional): If specified, will return only the text before this
delimiter. Defaults to None.
regex (Union[bool, str], optional): If True, `start` and `end` will be
treated as regular expressions. Optionally, can pass in python regex
flags separated by `|` characters, e.g "IGNORECASE|MULTILINE". Defaults
to False.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
Union[str, markupsafe.Markup]: Returns the output of the command.
"""
```
<!---->
### 🌀 path
Used several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).
Documentation:
<!---->
```py
def path(path: str,
*,
escape: bool = False,
indent: Union[str, int, None] = None,
indented: Union[str, int, None] = None,
backtickify: Union[bool, str] = False,
decomentify: Union[bool, Literal['nl']] = False,
link: Optional[Literal['md', 'html']] = None,
text: Optional[str] = None,
_ctx: _Context) -> Union[str, markupsafe.Markup]:
"""Verifies that `path` exists, and just returns `path`.
Unfortunately, I don't know how to use this inside a link, because the
formatters will destroy it, and it cannot be put into a code block (as the url
section of a link in markdown does not allow code blocks).
Args:
path (str): The path to verify.
escape (bool, optional): Should use HTML entities escaping? Defaults to
False.
indent (Union[str, int, None], optional): Should indent? By how much, or
with what prefix? Defaults to None.
indented (Union[str, int, None], optional): Indents every line except the
first. By how much, or with what prefix? Defaults to None.
backtickify (Union[bool, str], optional): Should surround with backticks?
With what language? Defaults to False.
decomentify (Union[bool, Literal['nl']], optional): Assuming that you will
be using HTML comments around this call, setting this to true will add
correspondingcomments to uncomment the output. This allows you to have
the Jinja2 call unmolested by markdown formatters, because they will be
inside of a comment section. "nl" adds additional newlines after the
newline delimiters. Defaults to False.
link (Literal['md', 'html'], optional): If specified, will
return a markdown or html link to the path. Defaults to None.
text (str, optional): If specified, will use this text as the
return value instead of the path. If used with link, will return this
text as the link text instead of the path. Defaults to None.
_ctx (_Context): This is used by the system and is not available as an
argument.
Returns:
Union[str, markupsafe.Markup]: Just returns the path. If the path doesn't
exist, it will raise an error.
"""
```
<!---->
## ✅ Requirements
- Linux-like environment
- Why: Uses pexpect.spawn().
- Python 3.8+
- Why: Some dev dependencies require Python 3.8+.
### Tested Platforms
- WSL2 Ubuntu 20.04, Python `3.8.0`.
- Ubuntu 20.04, Python `3.8.0, 3.9.0, 3.10.0, 3.11.0, 3.12.0`, tested in GitHub Actions
workflow ([build-and-test.yml](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/workflows/build-and-test.yml)).
## 🐳 Docker Image
Docker images are published to [ghcr.io/realazthat/snipinator][49] at each
tag.
<!---->
```bash
# View the template file.
cat "snipinator/examples/SIMPLE.md.jinja2"
# Use the published images at ghcr.io/realazthat/snipinator.
# /data in the docker image is the working directory, so paths are simpler.
docker run --rm --tty \
-u "$(id -u):$(id -g)" \
-v "${PWD}:/data" \
ghcr.io/realazthat/snipinator:v3.1.2 \
-t "snipinator/examples/SIMPLE.md.jinja2" \
--rm \
--force \
--create \
-o "snipinator/examples/SIMPLE.generated.md" \
--chmod-ro \
--skip-unchanged
# View the generated file.
cat "snipinator/examples/SIMPLE.generated.md"
```
<!---->
If you want to build the image yourself, you can use the Dockerfile in the
repository.
<!---->
```bash
docker build -t my-snipinator-image .
# View the template file.
cat "snipinator/examples/SIMPLE.md.jinja2"
# /data in the docker image is the working directory, so paths are simpler.
docker run --rm --tty \
-u "$(id -u):$(id -g)" \
-v "${PWD}:/data" \
my-snipinator-image \
-t "snipinator/examples/SIMPLE.md.jinja2" \
--rm \
--force \
--create \
-o "snipinator/examples/SIMPLE.generated.md" \
--chmod-ro \
--skip-unchanged
# View the generated file.
cat "snipinator/examples/SIMPLE.generated.md"
```
<!---->
## 🚸 Gotchas and Limitations
- **Security:** This tool is NOT designed to be used with untrusted input. It is
designed to be used with your own codebase. Even when using your own input, be
careful that your own code won't be doing anything that might inadvertently
include untrusted input.
- Be careful to escape `{{` and `}}`,
or `{%` and `%}` or anything jinja2
is sensitive to, in the templates. You'll have to escape it properly for
jinja2, which involves using `{% raw %}` and
`{% endraw %}` tags.
- Recursion: Snipinator doesn't directly support recursive
inclusion of generated content. You can generate the contents of one file
first, and include that generated content into another template. This would
mean that you have to worry about order of generation.
- Embedded Backticks: If there are backticks in the included snippet, it might
ruin the backticks you have in your markdown. This is why `backtickify`
parameter exists in the API, so that Snipinator provides the
backticks, and it will detect if there are backticks in the snippet and use a
different number of backticks on the entire snippet. So if the snippet
contains ` ```My Snippet``` `, Snipinator will use
` ````language ```My Snippet``` ```` ` and this is a method that Markdown uses
to allow embedded backticks inside a code block.
- Formatting: The `{{` `}}` used to
surround the snippet calls will unfortunately be formatted by a Markdown
formatter and make the call invalid. Workarounds:
- **Decommentify**: Put the snippet call inside a HTML comment, then use
`decommentify` parameter. See
[./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2) for
examples.
- [prettier](https://prettier.io/) formatter is pretty good at leaving the
Jinja2 calls alone, especially if you don't have any spaces. This especially
helps for markdown "reference-style links" that have Jinja2 calls in them
generating part of the URL, mdformat will URL encode the Jinja2 calls,
and/or split them on spaces, which is not what we want. prettier will leave
them alone.
- For code blocks: If you embed the snippet call in a code block, it will not
be formatted. However, because of **Embedded Backticks** gotcha, (see
above), this is not recommended, unless you know for sure that there are no
embedded backticks.
- If your formatter supports a comment that disabled formatting, you can
surround the snippet call with that comment.
- Editing the wrong file: When you have a template and a generated file, it is
easy to edit the wrong file. To combat this:
- Snipinator provides a warning at the top of the generated file
to remind you that it is auto-generated.
- Snipinator will optionally chmod the file for you to make it
read-only.
- Newlines: This program assumes LF newlines. I don't know if it will work for
anything else.
- Combining `backtickify` and `indent`: Doesn't make much sense, but if you do
it, it will run backtickify first, then indent everything including the
backticks.
## 🤏 Versioning
We use SemVer for versioning. For the versions available, see the tags on this
repository.
## 🔑 License
This project is licensed under the MIT License - see the
[./LICENSE.md](https://github.com/realazthat/snipinator/blob/v3.1.2/LICENSE.md) file for details.
## 🙏 Thanks
Main libraries used in Snipinator are:
- Templating: [Jinja2](https://github.com/pallets/jinja).
- Snippet inclusion: Python's AST library.
- Colorful CLI help: [rich-argparse](https://github.com/hamdanal/rich-argparse).
- ANSI coloring shell output:
{[pexpect](https://pexpect.readthedocs.io/en/stable/),
[rich](https://github.com/Textualize/rich)}.
## 🤝 Related Projects
Not complete, and not necessarily up to date. Make a PR
([contributions](#-contributions)) to insert/modify.
| Project | Stars | Last Update | Language | Platform | Similarity X Obviousness |
| ------------------------------------------------------------------- | --------- | ------------ | ---------- | ------------------------ | ------------------------ |
| [mdx-js / mdx][50] | 16.8k | `2024/04/17` | JS | N/A | ⭐⭐⭐⭐⭐ |
| [fletcher / MultiMarkdown-6][51] | 599 | `2023/12/30` | C | CLI | ⭐⭐⭐⭐⭐ |
| [gajus / gitdown][52] | 448 | `2022/03/01` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [gpoore / codebraid][53] | 362 | `2023/10/17` | Python | CLI | ⭐⭐⭐⭐⭐ |
| [amyreese / markdown-pp][54] (archived) | 307 | `2021/09/02` | Python | CLI | ⭐⭐⭐⭐⭐ |
| [zakhenry / embedme][55] | 222 | `2023/11/08` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [DCsunset / pandoc-include][56] | 62 | `2024/04/30` | Python | Pandoc / CLI | ⭐⭐⭐⭐⭐ |
| [BurdetteLamar / markdown_helper][57] | 38 | `2020/03/16` | Ruby | CLI | ⭐⭐⭐⭐⭐ |
| [SimonCropp / MarkdownSnippets][58] | 23 | `2024/04/23` | .NET | CLI | ⭐⭐⭐⭐⭐ |
| [endocode / snippetextractor][59] | 4 | `2014/08/16` | C++ | CLI | ⭐⭐⭐⭐⭐ |
| [polywrap / doc-snippets][60] | 3 | `2023/09/26` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [hxtmike / markdown_include][61] | 2 | `2024/05/09` | Python | CLI | ⭐⭐⭐⭐⭐ |
| [JulianCataldo / remark-embed][62] | 2 | `2022/09/22` | JS | JS / library | ⭐⭐⭐⭐⭐ |
| [xrd / oreilly-snippets][63] | 2 | `2015/10/15` | Ruby | Ruby / library | ⭐⭐⭐⭐⭐ |
| [DamonOehlman / injectcode][64] | 1 | `2021/08/01` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [electrovir / markdown-code-example-inserter][65] | 1 | `2024/02/19` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [andersfischernielsen / Simple-Embedded-Markdown-Code-Snippets][66] | 1 | `2021/02/12` | JS | CLI | ⭐⭐⭐⭐⭐ |
| [ildar-shaimordanov / git-markdown-snippet][67] | 0 | `2021/09/14` | Perl | CLI | ⭐⭐⭐⭐⭐ |
| [marc-bouvier-graveyard / baldir_markdown][68] | 0 | `2020/06/15` | Python | CLI | ⭐⭐⭐⭐⭐ |
| [facelessuser / pymdown-extensions][69] ([snippets][70]) | 903 | `2024/05/05` | Python | Python / PyMarkdown | ⭐⭐⭐⭐ |
| [dineshsonachalam / markdown-autodocs][71] | 176 | `2022/09/19` | JS | GH Action | ⭐⭐⭐⭐ |
| [sethen / markdown-include][72] | 148 | `2017/10/26` | JS | CLI+config | ⭐⭐⭐⭐ |
| [cmacmackin / markdown-include][73] | 95 | `2023/02/07` | Python | Python / library | ⭐⭐⭐⭐ |
| [tokusumi / markdown-embed-code][74] | 28 | `2022/01/05` | Python | GH Action | ⭐⭐⭐⭐ |
| [sammndhr / gridsome-remark-embed-snippet][75] | 2 | `2021/06/14` | JS | [Gridsome][76] | ⭐⭐⭐⭐ |
| [NativeScript / markdown-snippet-injector][77] | 4 | `2019/01/24` | JS | CLI | ⭐⭐⭐⭐ |
| [fossunited/markdown-macros][78] | 0 | `2021/06/10` | Python | Python / Python-Markdown | ⭐⭐⭐⭐ |
| [fuxingloh / remark-code-import-replace][79] | 0 | `2022/12/21` | JS | Remark? | ⭐⭐⭐⭐ |
| [teyc / markdown-snippet][80] | 0 | `2024/01/22` | Powershell | Powershell / function | ⭐⭐⭐⭐ |
| [szkiba / mdcode][81] | 15 | `2014/02/12` | Go | CLI | ⭐⭐⭐ |
| [devincornell/pymddoc][82] | 0 | `2023/12/01` | Python | Python | ⭐⭐⭐ |
| [shiftkey / scribble][83] ([docs][84]) | 40 | `2013/08/08` | .NET | CLI | ⭐⭐ |
| [calebpeterson / jest-transformer-test-md][85] | 2 | `2020/08/21` | JS | Jest Tests | ⭐⭐ |
| [tjstankus / commitate][86] | 0 | `2014/05/29` | Ruby | CLI | ⭐ |
| [GitHub Docs: Creating a permanent link to a code snippet][87] | N/A | N/A | N/A | GitHub | ⭐ |
| [javierfernandes / markdown-exercises][88] | 1 | `2017/05/01` | JS | N/A | ⭐ |
| [gatsby-remark-embed-snippet][89] | N/A (55k) | `2024/01/23` | JS | [Gatsby][90] | ⭐ |
| [ARMmbed / snippet][91] ([docs][92]) | 6 | `2021/08/05` | Python | CLI | ⭐ |
| [drewavis / markdowninclude][93] | 1 | `2024/04/06` | JS | VSCode Extension | ? |
| [romnn / embedme][94] | 0 | `2024/04/18` | Go | N/A | ⭐ |
## 🫡 Contributions
### Development environment: Linux-like
- For running `pre.sh` (Linux-like environment).
- From [./.github/dependencies.yml](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/dependencies.yml), which is used for
the GH Action to do a fresh install of everything:
```yaml
bash: scripts.
findutils: scripts.
grep: tests.
xxd: tests.
git: scripts, tests.
xxhash: scripts (changeguard).
rsync: out-of-directory test.
expect: for `unbuffer`, useful to grab and compare ansi color symbols.
jq: dependency for [yq](https://github.com/kislyuk/yq), which is used to generate
the README; the README generator needs to use `tomlq` (which is a part of `yq`)
to query `pyproject.toml`.
unzip: scripts (pyenv).
curl: scripts (pyenv).
git-core: scripts (pyenv).
gcc: scripts (pyenv).
make: scripts (pyenv).
zlib1g-dev: scripts (pyenv).
libbz2-dev: scripts (pyenv).
libreadline-dev: scripts (pyenv).
libsqlite3-dev: scripts (pyenv).
libssl-dev: scripts (pyenv).
libffi-dev: bdist_wheel (otherwise `pip install .` fails). If installing pyenv, this
must be installed _first_.
```
- On Ubuntu: `sudo apt-get update` and then
`sudo apt-get install -y bash findutils grep xxd git xxhash rsync expect jq unzip curl git-core gcc make zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libssl-dev libffi-dev`.
- Requires `pyenv`, or an exact matching version of python as in
[./.python-version](https://github.com/realazthat/snipinator/blob/v3.1.2/.python-version) (which is currently
`3.8.0`).
- act (to run the GH Action locally):
- Requires nodejs.
- Requires Go.
- docker.
- Generate animation:
- docker
- docker (for building the docker image).
### Commit Process
1. (Optionally) Fork the `develop` branch.
2. Stage your files: `git add path/to/file.py`.
3. `bash ./scripts/pre.sh`, this will format, lint, and test the code.
4. `git status` check if anything changed (generated
[./README.md](https://github.com/realazthat/snipinator/blob/v3.1.2/README.md) for example), if so, `git add` the
changes, and go back to the previous step.
5. `git commit -m "..."`.
6. Make a PR to `develop` (or push to develop if you have the rights).
## 🔄🚀 Release Process
These instructions are for maintainers of the project.
1. In the `develop` branch, run `bash ./scripts/pre.sh` to ensure
everything is in order.
2. In the `develop` branch, bump the version in
[./pyproject.toml](https://github.com/realazthat/snipinator/blob/v3.1.2/pyproject.toml), following semantic versioning
principles. Also modify the `last_release` and `last_stable_release` in the
`[tool.snipinator-project-metadata]` table as appropriate. Run
`bash ./scripts/pre.sh` to ensure everything is in order.
3. In the `develop` branch, commit these changes with a message like
`"Prepare release X.Y.Z"`. (See the contributions section
[above](#commit-process)).
4. Merge the `develop` branch into the `master` branch:
`git checkout master && git merge develop --no-ff`.
5. `master` branch: Tag the release: Create a git tag for the release with
`git tag -a vX.Y.Z -m "Version X.Y.Z"`.
6. Publish to PyPI: Publish the release to PyPI with
`bash ./scripts/deploy-to-pypi.sh`.
7. Push to GitHub: Push the commit and tags to GitHub with
`git push && git push --tags`.
8. The `--no-ff` option adds a commit to the master branch for the merge, so
refork the develop branch from the master branch:
`git checkout develop && git merge master`.
9. Push the develop branch to GitHub: `git push origin develop`.
[1]: https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/logo-exported.svg
[2]: https://github.com/realazthat/snipinator
[3]: https://img.shields.io/badge/Audience-Developers-0A1E1E?style=plastic&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJsdWNpZGUgbHVjaWRlLXVzZXJzIj48cGF0aCBkPSJNMTYgMjF2LTJhNCA0IDAgMCAwLTQtNEg2YTQgNCAwIDAgMC00IDR2MiIvPjxjaXJjbGUgY3g9IjkiIGN5PSI3IiByPSI0Ii8+PHBhdGggZD0iTTIyIDIxdi0yYTQgNCAwIDAgMC0zLTMuODciLz48cGF0aCBkPSJNMTYgMy4xM2E0IDQgMCAwIDEgMCA3Ljc1Ii8+PC9zdmc+
[4]: https://img.shields.io/badge/Platform-Linux-0A1E1E?style=plastic&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJsdWNpZGUgbHVjaWRlLWxhcHRvcC1taW5pbWFsIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTIiIHg9IjMiIHk9IjQiIHJ4PSIyIiByeT0iMiIvPjxsaW5lIHgxPSIyIiB4Mj0iMjIiIHkxPSIyMCIgeTI9IjIwIi8+PC9zdmc+
[5]: https://img.shields.io/github/languages/top/realazthat/snipinator.svg?cacheSeconds=28800&style=plastic&color=0A1E1E
[6]: https://img.shields.io/github/license/realazthat/snipinator?style=plastic&color=0A1E1E
[7]: https://github.com/realazthat/snipinator/blob/v3.1.2/LICENSE.md
[8]: https://img.shields.io/pypi/v/snipinator?style=plastic&color=0A1E1E
[9]: https://pypi.org/project/snipinator/
[10]: https://img.shields.io/pypi/pyversions/snipinator?style=plastic&color=0A1E1E
[11]: https://github.com/realazthat/snipinator/tree/master
[12]: https://img.shields.io/github/actions/workflow/status/realazthat/snipinator/build-and-test.yml?branch=master&style=plastic
[13]: https://github.com/realazthat/snipinator/actions/workflows/build-and-test.yml
[14]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/master?style=plastic
[15]: https://github.com/realazthat/snipinator/compare/v3.1.2...master
[16]: https://img.shields.io/github/last-commit/realazthat/snipinator/master?style=plastic
[17]: https://github.com/realazthat/snipinator/commits/master
[18]: https://github.com/realazthat/snipinator/tree/develop
[19]: https://img.shields.io/github/actions/workflow/status/realazthat/snipinator/build-and-test.yml?branch=develop&style=plastic
[20]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/develop?style=plastic
[21]: https://github.com/realazthat/snipinator/compare/v3.1.2...develop
[22]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/develop?style=plastic
[23]: https://github.com/realazthat/snipinator/compare/v3.1.2...develop
[24]: https://img.shields.io/github/last-commit/realazthat/snipinator/develop?style=plastic
[25]: https://github.com/realazthat/snipinator/commits/develop
[26]: https://github.com/realazthat/snipinator
[27]: https://github.com/realazthat/snipinator/blob/376cb1d83124ad00ce7c2a887d713ac2a85b9258/README.md?plain=1
[28]: https://github.com/realazthat/snipinator/blob/376cb1d83124ad00ce7c2a887d713ac2a85b9258/scripts/generate-readme.sh#L20
[29]: https://github.com/realazthat/mdremotifier
[30]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/README.md.jinja2
[31]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/README.md?plain=1
[32]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/scripts/generate-readme.sh#L20
[33]: https://github.com/realazthat/changeguard
[34]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/README.md.jinja2
[35]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/README.md?plain=1
[36]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/scripts/generate-readme.sh#L20
[37]: https://github.com/realazthat/excalidraw-brute-export-cli
[38]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/README.md.jinja2
[39]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/README.md?plain=1
[40]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/scripts/generate-readme.sh#L65
[41]: https://github.com/realazthat/comfy-catapult
[42]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/README.md.jinja2
[43]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/README.md?plain=1
[44]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/scripts/gen-readme.sh#L17
[45]: https://github.com/realazthat/comfylowda
[46]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/README.md.jinja2
[47]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/README.md?plain=1
[48]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/scripts/gen-readme.sh#L19
[49]: https://ghcr.io/realazthat/snipinator
[50]: https://github.com/mdx-js/mdx
[51]: https://github.com/fletcher/MultiMarkdown-6
[52]: https://github.com/gajus/gitdown
[53]: https://github.com/gpoore/codebraid
[54]: https://github.com/amyreese/markdown-pp "Archived"
[55]: https://github.com/zakhenry/embedme
[56]: https://github.com/DCsunset/pandoc-include
[57]: https://github.com/BurdetteLamar/markdown_helper
[58]: https://github.com/SimonCropp/MarkdownSnippets
[59]: https://github.com/endocode/snippetextractor
[60]: https://github.com/polywrap/doc-snippets
[61]: https://github.com/hxtmike/markdown_include
[62]: https://github.com/JulianCataldo/remark-embed
[63]: https://github.com/xrd/oreilly-snippets
[64]: https://github.com/DamonOehlman/injectcode
[65]: https://github.com/electrovir/markdown-code-example-inserter
[66]: https://github.com/andersfischernielsen/Simple-Embedded-Markdown-Code-Snippets
[67]: https://github.com/ildar-shaimordanov/git-markdown-snippet
[68]: https://github.com/marc-bouvier-graveyard/baldir_markdown
[69]: https://github.com/facelessuser/pymdown-extensions
[70]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[71]: https://github.com/dineshsonachalam/markdown-autodocs
[72]: https://github.com/sethen/markdown-include "CLI but requires that you make a json file with various optiosn to produce the output"
[73]: https://github.com/cmacmackin/markdown-include
[74]: https://github.com/tokusumi/markdown-embed-code
[75]: https://github.com/sammndhr/gridsome-remark-embed-snippet
[76]: https://gridsome.org/
[77]: https://github.com/NativeScript/markdown-snippet-injector
[78]: https://github.com/fossunited/markdown-macros
[79]: https://github.com/fuxingloh/remark-code-import-replace
[80]: https://github.com/teyc/markdown-snippet
[81]: https://github.com/szkiba/mdcode "Extracts code blocks from README and produces tests; a similar approach, but quite different"
[82]: https://github.com/devincornell/pymddoc
[83]: https://github.com/shiftkey/scribble
[84]: https://github.com/shiftkey/scribble/blob/master/docs/features/code-snippets.md
[85]: https://github.com/calebpeterson/jest-transformer-test-md
[86]: https://github.com/tjstankus/commitate "Missing usage example"
[87]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet
[88]: https://github.com/javierfernandes/markdown-exercises "This doesn't embed files, rather allows markdown code sections to be tested, no usage example"
[89]: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-embed-snippet
[90]: https://github.com/gatsbyjs/gatsby
[91]: https://github.com/ARMmbed/snippet "Unclear from documentation on how to embed the code into the template"
[92]: https://github.com/ARMmbed/snippet/blob/master/USAGE.md
[93]: https://github.com/drewavis/markdowninclude
[94]: https://github.com/romnn/embedme "Documentation is lacking"
Raw data
{
"_id": null,
"home_page": null,
"name": "snipinator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "github, testing, markdown, readme, snippets, documentation, jinja2, templates, preprocessor, documentation-tool, include, readme-template, readme-md, dynamic-documentation",
"author": null,
"author_email": "AYF <realazthat@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0d/d5/a973753e0a5f70af5bbe18ece4afebe2261f3bd643f4970567fd466c310d/snipinator-3.1.2.tar.gz",
"platform": null,
"description": "<!--\n\nWARNING: This file is auto-generated by snipinator. Do not edit directly.\nSOURCE: `.github/README.md.jinja2`.\n\n-->\n<!--\n\n\n\n\n\n\n\n\n-->\n\n# <div align=\"center\">[![Snipinator][1]][2]</div>\n\n<div align=\"center\">\n\n<!-- Icons from https://lucide.dev/icons/users -->\n<!-- Icons from https://lucide.dev/icons/laptop-minimal -->\n\n![**Audience:** Developers][3] ![**Platform:** Linux][4]\n\n</div>\n\n<p align=\"center\">\n <strong>\n <a href=\"https://github.com/realazthat/snipinator\">\ud83c\udfe0Home</a>\n • \n <a href=\"#-features\">\ud83c\udf87Features</a>\n • \n <a href=\"#-install\">\ud83d\udd28Install</a>\n • \n <a href=\"#-usage\">\ud83d\ude9cUsage</a>\n • \n <a href=\"#-command-line-options\">\ud83d\udcbbCLI</a>\n • \n <a href=\"#-examples\">\ud83d\udca1Examples</a>\n </strong>\n</p>\n<p align=\"center\">\n <strong>\n <a href=\"#-jinja2-api\">\ud83e\udd16Jinja2 API</a>\n • \n <a href=\"#-requirements\">\u2705Requirements</a>\n • \n <a href=\"#-docker-image\">\ud83d\udc33Docker</a>\n • \n <a href=\"#-gotchas-and-limitations\">\ud83d\udeb8Gotchas</a>\n </strong>\n</p>\n\n<div align=\"center\">\n\n![Top language][5] [![GitHub License][6]][7] [![PyPI - Version][8]][9]\n[![Python Version][10]][9]\n\n**CLI to embed (testable) snippets from your codebase into your README**\n\n</div>\n\n---\n\n<div align=\"center\">\n\n| | Status | Stable | Unstable | |\n| ----------------- | --------------------------- | ------------------------- | ------------------------- | ------------------------ |\n| **[Master][11]** | [![Build and Test][12]][13] | [![since tagged][14]][15] | | [![last commit][16]][17] |\n| **[Develop][18]** | [![Build and Test][19]][13] | [![since tagged][20]][21] | [![since tagged][22]][23] | [![last commit][24]][25] |\n\n</div>\n\n<img alt=\"Demo\" src=\"https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/demo.gif\" width=\"100%\"/>\n\n## \u2754 What\n\nWhat it does: **Snipinator** lets you take a `EXAMPLE.md` template\nand include snippets from your (working and tested) codebase.\n\nTurn this ([./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2)):\n\n<!---->\n```md\n# A README\n\nHere is a code snippet:\n\n<!--{{ pysnippet(path='snipinator/examples/code.py', symbol='MyClass', backtickify='py', decomentify='nl') }}-->\n\nNote that `code.py` has a test:\n{{path('./snipinator/examples/code_test.py', link='md')}}.\n\n```\n<!---->\n\nInto this ([./snipinator/examples/SIMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.generated.md)):\n\n<!---->\n````md\n<!--\n\nWARNING: This file is auto-generated by snipinator. Do not edit directly.\nSOURCE: `snipinator/examples/SIMPLE.md.jinja2`.\n\n-->\n# A README\n\nHere is a code snippet:\n\n<!---->\n```py\nclass MyClass:\n \"\"\"This is a global class\"\"\"\n\n def __init__(self, name):\n self.name = name\n\n def MyClassMethod(self):\n \"\"\"This is a method of MyClass\"\"\"\n print(self.name)\n```\n<!---->\n\nNote that `code.py` has a test:\n[./snipinator/examples/code_test.py](./snipinator/examples/code_test.py).\n\n````\n<!---->\n\n## \ud83c\udf87 Features\n\n- \ud83d\udce6\u2705\ud83e\ude84 Supports anything **[Jinja2](https://github.com/pallets/jinja)**\n supports.\n- \ud83e\udd47\ud83d\udc0d\ud83d\udcdc First-class support for **python** source code.\n - Can include python function signatures, docstrings, entire function source\n code, classes.\n- \u2702\ud83c\udf10\ud83d\uddc2\ufe0f Snip from **any source code language**.\n - Put delimiter markers into the code (e.g `# START_SNIPPET`,\n `# END_TEMPLATE`), and use [snippet()](#snippet).\n- \ud83e\udd47\ud83d\udd16\ud83d\udcdc First-class support for **Markdown** templates (with `backtickify`,\n `decomentify`).\n- \ud83d\udce6\ud83d\udc1a\ud83d\udda8\ufe0f Can include **[shell](#shell) output**.\n - Supports ANSI colors :heart: :green_heart: :blue_heart: with SVG output\n :camera:.\n- \u2699\ufe0f\ud83d\udd17\ud83d\uddc3\ufe0f More robust **references/links** to local files using [path()](#path).\n- \ud83d\udc33\ud83c\udf0a\ud83d\udda5\ufe0f Docker Image (See [README: Docker Image](#-docker-image)).\n\n## \ud83d\udd28 Install\n\n```bash\n# Install from pypi (https://pypi.org/project/snipinator/)\npip install snipinator\n\n# Install from git (https://github.com/realazthat/snipinator)\npip install git+https://github.com/realazthat/snipinator.git@v3.1.2\n```\n\n## \ud83d\ude9c Usage\n\nExample template README:\n([./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2)):\n\n<!---->\n```md\n# A README\n\nHere is a code snippet:\n\n<!--{{ pysnippet(path='snipinator/examples/code.py', symbol='MyClass', backtickify='py', decomentify='nl') }}-->\n\nNote that `code.py` has a test:\n{{path('./snipinator/examples/code_test.py', link='md')}}.\n\n```\n<!---->\n\nGenerating the README:\n\n<!---->\n````bash\n$ python -m snipinator.cli -t snipinator/examples/SIMPLE.md.jinja2\n<!--\n\nWARNING: This file is auto-generated by snipinator. Do not edit directly.\nSOURCE: `snipinator/examples/SIMPLE.md.jinja2`.\n\n-->\n# A README\n\nHere is a code snippet:\n\n<!---->\n```py\nclass MyClass:\n \"\"\"This is a global class\"\"\"\n\n def __init__(self, name):\n self.name = name\n\n def MyClassMethod(self):\n \"\"\"This is a method of MyClass\"\"\"\n print(self.name)\n```\n<!---->\n\nNote that `code.py` has a test:\n[./snipinator/examples/code_test.py](./snipinator/examples/code_test.py).\n\n````\n<!---->\n\nFuller example:\n\n<!---->\n<img alt=\"Output of `bash ./snipinator/examples/simple_example.sh`\" src=\"https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/README.example.generated.svg\"/>\n<!-- -->\n\n## \ud83d\udcbb Command Line Options\n\n<!---->\n<img alt=\"Output of `python -m snipinator.cli --help`\" src=\"https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/README.help.generated.svg\"/>\n<!-- -->\n\n## \ud83d\udca1 Examples\n\n- Snipinator's own `README`:\n - Template: [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n - Generated: [./README.md](https://github.com/realazthat/snipinator/blob/v3.1.2/README.md).\n - Generation script: [./scripts/generate-readme.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/scripts/generate-readme.sh).\n- Example:\n - Template: [./snipinator/examples/SIMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.md.jinja2).\n - Generated: [./snipinator/examples/SIMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/SIMPLE.generated.md).\n - Generation script:\n [./snipinator/examples/simple_example.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/simple_example.sh).\n- Long example of many features:\n - Template:\n [./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).\n - Generated:\n [./snipinator/examples/LONG-EXAMPLE.generated.md](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.generated.md).\n - Generation script:\n [./snipinator/examples/long_example.sh](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/long_example.sh).\n- Projects using Snipinator:\n - [realazthat/snipinator][26]\n - Template: [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n - Generated: [snipinator/README.md][27].\n - Generation script: [snipinator/scripts/generate-readme.sh#L20][28].\n - [realazthat/mdremotifier][29].\n - Template: [mdremotifier/README.md.jinja2][30].\n - Generated: [mdremotifier/README.md][31].\n - Generation script: [mdremotifier/generate-readme.sh#L20][32].\n - [realazthat/changeguard][33].\n - Template: [changeguard/README.md.jinja2][34].\n - Generated: [changeguard/README.md][35].\n - Generation script: [changeguard/generate-readme.sh#L20][36].\n - [realazthat/excalidraw-brute-export-cli][37],\n - Template: [excalidraw-brute-export-cli/README.md.jinja2][38].\n - Generated: [excalidraw-brute-export-cli/README.md][39].\n - Generation script:\n [excalidraw-brute-export-cli/generate-readme.sh#L65][40].\n - [realazthat/comfy-catapult][41].\n - Template: [comfy-catapult/README.md.jinja2][42].\n - Generated: [comfy-catapult/README.md][43].\n - Generation script: [comfy-catapult/generate-readme.sh#L17][44].\n - [realazthat/comfylowda][45].\n - Template: [comfylowda/README.md.jinja2][46].\n - Generated: [comfylowda/README.md][47].\n - Generation script: [comfylowda/generate-readme.sh#L17][48].\n\n## \ud83e\udd16 Jinja2 API\n\nThe regular Jinja2 v3 template syntax is supported. For more information, see\n[Template Designer Documentation](https://jinja.palletsprojects.com/en/3.1.x/templates/).\n\nAdditional (Jinja2) functions made available:\n\n### \ud83d\udc0d\u2702 pysnippet\n\nUsed several times in\n[./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef pysnippet(path: str,\n symbol: Optional[str],\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n _ctx: _Context) -> Union[str, markupsafe.Markup]:\n \"\"\"Return a python snippet, allowing you to specify a class or function.\n\n Args:\n path (str): The path to the file.\n symbol (Optional[str]): The symbol to extract. If None, the entire file is\n returned. Defaults to None.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (Union[bool, Literal['nl']], optional): Assuming that you will\n be using HTML comments around this call, setting this to true will add\n correspondingcomments to uncomment the output. This allows you to have\n the Jinja2 call unmolested by markdown formatters, because they will be\n inside of a comment section. \"nl\" adds additional newlines after the\n newline delimiters. Defaults to False.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n Union[str, markupsafe.Markup]: The snippet.\n \"\"\"\n```\n<!---->\n\n### \ud83d\udc0d\ud83d\udcd6 pysignature\n\nUsed several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef pysignature(path: str,\n symbol: str,\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n _ctx: _Context) -> str:\n \"\"\"Return the signature of a class or function in a python file.\n\n Returns the {class,function} signature and the docstring.\n\n Args:\n path (str): The path to the file.\n symbol (str): The symbol to extract.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (Union[bool, Literal['nl']], optional): Assuming that you will\n be using HTML comments around this call, setting this to true will add\n correspondingcomments to uncomment the output. This allows you to have\n the Jinja2 call unmolested by markdown formatters, because they will be\n inside of a comment section. \"nl\" adds additional newlines after the\n newline delimiters. Defaults to False.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n str: The signature and docstring.\n \"\"\"\n```\n<!---->\n\n### \u2702 rawsnippet\n\nUsed several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef rawsnippet(path: str,\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n _ctx: _Context) -> Union[str, markupsafe.Markup]:\n \"\"\"Return an entire file as a snippet.\n\n Args:\n path (str): The path to the file.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (Union[bool, Literal['nl']], optional): Assuming that you will\n be using HTML comments around this call, setting this to true will add\n correspondingcomments to uncomment the output. This allows you to have\n the Jinja2 call unmolested by markdown formatters, because they will be\n inside of a comment section. \"nl\" adds additional newlines after the\n newline delimiters. Defaults to False.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n Union[str, markupsafe.Markup]: The snippet.\n \"\"\"\n\n```\n<!---->\n\n### \u2702 snippet\n\nExample in [./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef snippet(path: str,\n start: str,\n end: str,\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n regex: Union[bool, str] = False,\n _ctx: _Context) -> Union[str, markupsafe.Markup]:\n \"\"\"Returns a _delimited_ snippet from a file.\n\n Does not return the delimiters themselves.\n\n Args:\n path (str): The path to the file.\n start (str): A string that indicates the start of the snippet.\n end (str): A string that indicates the end of the snippet.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (Union[bool, Literal['nl']], optional): Assuming that you will\n be using HTML comments around this call, setting this to true will add\n correspondingcomments to uncomment the output. This allows you to have\n the Jinja2 call unmolested by markdown formatters, because they will be\n inside of a comment section. \"nl\" adds additional newlines after the\n newline delimiters. Defaults to False.\n regex (Union[bool, str], optional): If True, `start` and `end` will be\n treated as regular expressions. Optionally, can pass in python regex\n flags separated by `|` characters, e.g \"IGNORECASE|MULTILINE\". Defaults\n to False.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n Union[str, markupsafe.Markup]: The snippet.\n \"\"\"\n\n```\n<!---->\n\n### \ud83d\udc1a shell\n\nUsed several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef shell(args: str,\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n rich: Union[Literal['svg'], Literal['img+b64+svg'], Literal['raw'],\n str] = 'raw',\n rich_alt: Optional[str] = None,\n rich_bg_color: Optional[str] = None,\n rich_term: Optional[str] = None,\n rich_rows: int = 24,\n rich_cols: int = 80,\n include_args: bool = True,\n start: Optional[str] = None,\n end: Optional[str] = None,\n regex: Union[bool, str] = False,\n _ctx: _Context) -> Union[str, markupsafe.Markup]:\n \"\"\"Run a shell command and return the output.\n\n Use at your own risk, this can potentially introduce security vulnerabilities.\n Only use if you know what you are doing. Ensure that no untrusted input can\n be injected into the `args` parameter, or, into anything the command might\n access. If an adversary can control the `args` parameter, they can execute\n arbitrary commands on your system.\n\n Note: On persistent output colors:\n\n * I found that the environment variables TERM, COLORTERM and FORCE_COLOR,\n CLI_WIDTH, COLUMNS also influence the outputs for some applications.\n * Also various library versions used in various programs, e.g colorama,\n rich-argparse, Pygments might influence the output.\n * I had to pin all my python packages, and explicitly set TERM, COLORTERM and\n FORCE_COLOR, CLI_WIDTH, COLUMNS to get the output to be consistent across\n two different systems, both using Ubuntu, for a single program.\n\n Args:\n args (str): The command to run.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (bool, optional): Assuming that you will be using HTML\n comments around this call, setting this to true will add corresponding\n uncomments to uncomment the output. This allows you to have the Jinja2\n call unmolested by markdown formatters, because they will be inside of\n a comment section. Defaults to False.\n rich (Union[Literal['svg'], Literal['img+b64+svg'], Literal['raw'], str],\n optional):\n Optionally outputs colored terminal output as an image.\n * If `rich` is a relative file path that ends with \".svg\", the svg will\n be saved to that location and an img tag will be emitted. The path\n will be relative to the template file, which is specified on the\n command line. If the template is from stdin, the path will be relative\n to the current working directory (cwd) which is also specified on the\n command line.\n * If 'svg' a raw svg tag will be dumped into the markdown with the\n colored terminal output. Note that your markdown renderer may not\n support this.\n * If 'img+svg' a base64 encoded image will be dumped into the markdown\n with the colored terminal output.\n * If 'raw' the raw (uncolored) terminal output will be dumped into the\n markdown directly.\n * Defaults to 'raw.\n rich_alt (str, optional): The alt text for the img tag. Defaults\n to None.\n rich_bg_color (str, optional): The background color for the\n terminal output. Valid colors include anything valid for SVG colors. See\n <https://developer.mozilla.org/en-US/docs/Web/CSS/color>. Defaults to\n None (fully transparent).\n rich_term: (str, optional): Sets the TERM env var. Defaults to\n None, which uses whatever the env vars already have.\n rich_rows (int, optional): The number of rows to use for the terminal\n output. Doesn't seem to have much effect. Defaults to 24.\n rich_cols (int, optional): The number of columns to use for the terminal\n output. Defaults to 80.\n include_args (bool, optional): Should include the command that was run in\n the output? Defaults to True.\n start (str, optional): If specified, will return only the text after this\n delimiter. Defaults to None.\n end (str, optional): If specified, will return only the text before this\n delimiter. Defaults to None.\n regex (Union[bool, str], optional): If True, `start` and `end` will be\n treated as regular expressions. Optionally, can pass in python regex\n flags separated by `|` characters, e.g \"IGNORECASE|MULTILINE\". Defaults\n to False.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n Union[str, markupsafe.Markup]: Returns the output of the command.\n \"\"\"\n```\n<!---->\n\n### \ud83c\udf00 path\n\nUsed several times in [./.github/README.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/README.md.jinja2).\n\nDocumentation:\n\n<!---->\n```py\ndef path(path: str,\n *,\n escape: bool = False,\n indent: Union[str, int, None] = None,\n indented: Union[str, int, None] = None,\n backtickify: Union[bool, str] = False,\n decomentify: Union[bool, Literal['nl']] = False,\n link: Optional[Literal['md', 'html']] = None,\n text: Optional[str] = None,\n _ctx: _Context) -> Union[str, markupsafe.Markup]:\n \"\"\"Verifies that `path` exists, and just returns `path`.\n\n Unfortunately, I don't know how to use this inside a link, because the\n formatters will destroy it, and it cannot be put into a code block (as the url\n section of a link in markdown does not allow code blocks).\n\n Args:\n path (str): The path to verify.\n escape (bool, optional): Should use HTML entities escaping? Defaults to\n False.\n indent (Union[str, int, None], optional): Should indent? By how much, or\n with what prefix? Defaults to None.\n indented (Union[str, int, None], optional): Indents every line except the\n first. By how much, or with what prefix? Defaults to None.\n backtickify (Union[bool, str], optional): Should surround with backticks?\n With what language? Defaults to False.\n decomentify (Union[bool, Literal['nl']], optional): Assuming that you will\n be using HTML comments around this call, setting this to true will add\n correspondingcomments to uncomment the output. This allows you to have\n the Jinja2 call unmolested by markdown formatters, because they will be\n inside of a comment section. \"nl\" adds additional newlines after the\n newline delimiters. Defaults to False.\n link (Literal['md', 'html'], optional): If specified, will\n return a markdown or html link to the path. Defaults to None.\n text (str, optional): If specified, will use this text as the\n return value instead of the path. If used with link, will return this\n text as the link text instead of the path. Defaults to None.\n _ctx (_Context): This is used by the system and is not available as an\n argument.\n\n Returns:\n Union[str, markupsafe.Markup]: Just returns the path. If the path doesn't\n exist, it will raise an error.\n \"\"\"\n```\n<!---->\n\n## \u2705 Requirements\n\n- Linux-like environment\n - Why: Uses pexpect.spawn().\n- Python 3.8+\n - Why: Some dev dependencies require Python 3.8+.\n\n### Tested Platforms\n\n- WSL2 Ubuntu 20.04, Python `3.8.0`.\n- Ubuntu 20.04, Python `3.8.0, 3.9.0, 3.10.0, 3.11.0, 3.12.0`, tested in GitHub Actions\n workflow ([build-and-test.yml](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/workflows/build-and-test.yml)).\n\n## \ud83d\udc33 Docker Image\n\nDocker images are published to [ghcr.io/realazthat/snipinator][49] at each\ntag.\n\n<!---->\n```bash\n\n# View the template file.\ncat \"snipinator/examples/SIMPLE.md.jinja2\"\n\n# Use the published images at ghcr.io/realazthat/snipinator.\n# /data in the docker image is the working directory, so paths are simpler.\ndocker run --rm --tty \\\n -u \"$(id -u):$(id -g)\" \\\n -v \"${PWD}:/data\" \\\n ghcr.io/realazthat/snipinator:v3.1.2 \\\n -t \"snipinator/examples/SIMPLE.md.jinja2\" \\\n --rm \\\n --force \\\n --create \\\n -o \"snipinator/examples/SIMPLE.generated.md\" \\\n --chmod-ro \\\n --skip-unchanged\n\n# View the generated file.\ncat \"snipinator/examples/SIMPLE.generated.md\"\n\n```\n<!---->\n\nIf you want to build the image yourself, you can use the Dockerfile in the\nrepository.\n\n<!---->\n```bash\n\ndocker build -t my-snipinator-image .\n\n# View the template file.\ncat \"snipinator/examples/SIMPLE.md.jinja2\"\n\n# /data in the docker image is the working directory, so paths are simpler.\ndocker run --rm --tty \\\n -u \"$(id -u):$(id -g)\" \\\n -v \"${PWD}:/data\" \\\n my-snipinator-image \\\n -t \"snipinator/examples/SIMPLE.md.jinja2\" \\\n --rm \\\n --force \\\n --create \\\n -o \"snipinator/examples/SIMPLE.generated.md\" \\\n --chmod-ro \\\n --skip-unchanged\n\n# View the generated file.\ncat \"snipinator/examples/SIMPLE.generated.md\"\n\n```\n<!---->\n\n## \ud83d\udeb8 Gotchas and Limitations\n\n- **Security:** This tool is NOT designed to be used with untrusted input. It is\n designed to be used with your own codebase. Even when using your own input, be\n careful that your own code won't be doing anything that might inadvertently\n include untrusted input.\n- Be careful to escape `{{` and `}}`,\n or `{%` and `%}` or anything jinja2\n is sensitive to, in the templates. You'll have to escape it properly for\n jinja2, which involves using `{% raw %}` and\n `{% endraw %}` tags.\n- Recursion: Snipinator doesn't directly support recursive\n inclusion of generated content. You can generate the contents of one file\n first, and include that generated content into another template. This would\n mean that you have to worry about order of generation.\n- Embedded Backticks: If there are backticks in the included snippet, it might\n ruin the backticks you have in your markdown. This is why `backtickify`\n parameter exists in the API, so that Snipinator provides the\n backticks, and it will detect if there are backticks in the snippet and use a\n different number of backticks on the entire snippet. So if the snippet\n contains ` ```My Snippet``` `, Snipinator will use\n ` ````language ```My Snippet``` ```` ` and this is a method that Markdown uses\n to allow embedded backticks inside a code block.\n- Formatting: The `{{` `}}` used to\n surround the snippet calls will unfortunately be formatted by a Markdown\n formatter and make the call invalid. Workarounds:\n - **Decommentify**: Put the snippet call inside a HTML comment, then use\n `decommentify` parameter. See\n [./snipinator/examples/LONG-EXAMPLE.md.jinja2](https://github.com/realazthat/snipinator/blob/v3.1.2/snipinator/examples/LONG-EXAMPLE.md.jinja2) for\n examples.\n - [prettier](https://prettier.io/) formatter is pretty good at leaving the\n Jinja2 calls alone, especially if you don't have any spaces. This especially\n helps for markdown \"reference-style links\" that have Jinja2 calls in them\n generating part of the URL, mdformat will URL encode the Jinja2 calls,\n and/or split them on spaces, which is not what we want. prettier will leave\n them alone.\n - For code blocks: If you embed the snippet call in a code block, it will not\n be formatted. However, because of **Embedded Backticks** gotcha, (see\n above), this is not recommended, unless you know for sure that there are no\n embedded backticks.\n - If your formatter supports a comment that disabled formatting, you can\n surround the snippet call with that comment.\n- Editing the wrong file: When you have a template and a generated file, it is\n easy to edit the wrong file. To combat this:\n - Snipinator provides a warning at the top of the generated file\n to remind you that it is auto-generated.\n - Snipinator will optionally chmod the file for you to make it\n read-only.\n- Newlines: This program assumes LF newlines. I don't know if it will work for\n anything else.\n- Combining `backtickify` and `indent`: Doesn't make much sense, but if you do\n it, it will run backtickify first, then indent everything including the\n backticks.\n\n## \ud83e\udd0f Versioning\n\nWe use SemVer for versioning. For the versions available, see the tags on this\nrepository.\n\n## \ud83d\udd11 License\n\nThis project is licensed under the MIT License - see the\n[./LICENSE.md](https://github.com/realazthat/snipinator/blob/v3.1.2/LICENSE.md) file for details.\n\n## \ud83d\ude4f Thanks\n\nMain libraries used in Snipinator are:\n\n- Templating: [Jinja2](https://github.com/pallets/jinja).\n- Snippet inclusion: Python's AST library.\n- Colorful CLI help: [rich-argparse](https://github.com/hamdanal/rich-argparse).\n- ANSI coloring shell output:\n {[pexpect](https://pexpect.readthedocs.io/en/stable/),\n [rich](https://github.com/Textualize/rich)}.\n\n## \ud83e\udd1d Related Projects\n\nNot complete, and not necessarily up to date. Make a PR\n([contributions](#-contributions)) to insert/modify.\n\n| Project | Stars | Last Update | Language | Platform | Similarity X Obviousness |\n| ------------------------------------------------------------------- | --------- | ------------ | ---------- | ------------------------ | ------------------------ |\n| [mdx-js / mdx][50] | 16.8k | `2024/04/17` | JS | N/A | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [fletcher / MultiMarkdown-6][51] | 599 | `2023/12/30` | C | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [gajus / gitdown][52] | 448 | `2022/03/01` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [gpoore / codebraid][53] | 362 | `2023/10/17` | Python | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [amyreese / markdown-pp][54] (archived) | 307 | `2021/09/02` | Python | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [zakhenry / embedme][55] | 222 | `2023/11/08` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [DCsunset / pandoc-include][56] | 62 | `2024/04/30` | Python | Pandoc / CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [BurdetteLamar / markdown_helper][57] | 38 | `2020/03/16` | Ruby | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [SimonCropp / MarkdownSnippets][58] | 23 | `2024/04/23` | .NET | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [endocode / snippetextractor][59] | 4 | `2014/08/16` | C++ | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [polywrap / doc-snippets][60] | 3 | `2023/09/26` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [hxtmike / markdown_include][61] | 2 | `2024/05/09` | Python | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [JulianCataldo / remark-embed][62] | 2 | `2022/09/22` | JS | JS / library | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [xrd / oreilly-snippets][63] | 2 | `2015/10/15` | Ruby | Ruby / library | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [DamonOehlman / injectcode][64] | 1 | `2021/08/01` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [electrovir / markdown-code-example-inserter][65] | 1 | `2024/02/19` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [andersfischernielsen / Simple-Embedded-Markdown-Code-Snippets][66] | 1 | `2021/02/12` | JS | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [ildar-shaimordanov / git-markdown-snippet][67] | 0 | `2021/09/14` | Perl | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [marc-bouvier-graveyard / baldir_markdown][68] | 0 | `2020/06/15` | Python | CLI | \u2b50\u2b50\u2b50\u2b50\u2b50 |\n| [facelessuser / pymdown-extensions][69] ([snippets][70]) | 903 | `2024/05/05` | Python | Python / PyMarkdown | \u2b50\u2b50\u2b50\u2b50 |\n| [dineshsonachalam / markdown-autodocs][71] | 176 | `2022/09/19` | JS | GH Action | \u2b50\u2b50\u2b50\u2b50 |\n| [sethen / markdown-include][72] | 148 | `2017/10/26` | JS | CLI+config | \u2b50\u2b50\u2b50\u2b50 |\n| [cmacmackin / markdown-include][73] | 95 | `2023/02/07` | Python | Python / library | \u2b50\u2b50\u2b50\u2b50 |\n| [tokusumi / markdown-embed-code][74] | 28 | `2022/01/05` | Python | GH Action | \u2b50\u2b50\u2b50\u2b50 |\n| [sammndhr / gridsome-remark-embed-snippet][75] | 2 | `2021/06/14` | JS | [Gridsome][76] | \u2b50\u2b50\u2b50\u2b50 |\n| [NativeScript / markdown-snippet-injector][77] | 4 | `2019/01/24` | JS | CLI | \u2b50\u2b50\u2b50\u2b50 |\n| [fossunited/markdown-macros][78] | 0 | `2021/06/10` | Python | Python / Python-Markdown | \u2b50\u2b50\u2b50\u2b50 |\n| [fuxingloh / remark-code-import-replace][79] | 0 | `2022/12/21` | JS | Remark? | \u2b50\u2b50\u2b50\u2b50 |\n| [teyc / markdown-snippet][80] | 0 | `2024/01/22` | Powershell | Powershell / function | \u2b50\u2b50\u2b50\u2b50 |\n| [szkiba / mdcode][81] | 15 | `2014/02/12` | Go | CLI | \u2b50\u2b50\u2b50 |\n| [devincornell/pymddoc][82] | 0 | `2023/12/01` | Python | Python | \u2b50\u2b50\u2b50 |\n| [shiftkey / scribble][83] ([docs][84]) | 40 | `2013/08/08` | .NET | CLI | \u2b50\u2b50 |\n| [calebpeterson / jest-transformer-test-md][85] | 2 | `2020/08/21` | JS | Jest Tests | \u2b50\u2b50 |\n| [tjstankus / commitate][86] | 0 | `2014/05/29` | Ruby | CLI | \u2b50 |\n| [GitHub Docs: Creating a permanent link to a code snippet][87] | N/A | N/A | N/A | GitHub | \u2b50 |\n| [javierfernandes / markdown-exercises][88] | 1 | `2017/05/01` | JS | N/A | \u2b50 |\n| [gatsby-remark-embed-snippet][89] | N/A (55k) | `2024/01/23` | JS | [Gatsby][90] | \u2b50 |\n| [ARMmbed / snippet][91] ([docs][92]) | 6 | `2021/08/05` | Python | CLI | \u2b50 |\n| [drewavis / markdowninclude][93] | 1 | `2024/04/06` | JS | VSCode Extension | ? |\n| [romnn / embedme][94] | 0 | `2024/04/18` | Go | N/A | \u2b50 |\n\n## \ud83e\udee1 Contributions\n\n### Development environment: Linux-like\n\n- For running `pre.sh` (Linux-like environment).\n\n - From [./.github/dependencies.yml](https://github.com/realazthat/snipinator/blob/v3.1.2/.github/dependencies.yml), which is used for\n the GH Action to do a fresh install of everything:\n\n ```yaml\n bash: scripts.\n findutils: scripts.\n grep: tests.\n xxd: tests.\n git: scripts, tests.\n xxhash: scripts (changeguard).\n rsync: out-of-directory test.\n expect: for `unbuffer`, useful to grab and compare ansi color symbols.\n jq: dependency for [yq](https://github.com/kislyuk/yq), which is used to generate\n the README; the README generator needs to use `tomlq` (which is a part of `yq`)\n to query `pyproject.toml`.\n unzip: scripts (pyenv).\n curl: scripts (pyenv).\n git-core: scripts (pyenv).\n gcc: scripts (pyenv).\n make: scripts (pyenv).\n zlib1g-dev: scripts (pyenv).\n libbz2-dev: scripts (pyenv).\n libreadline-dev: scripts (pyenv).\n libsqlite3-dev: scripts (pyenv).\n libssl-dev: scripts (pyenv).\n libffi-dev: bdist_wheel (otherwise `pip install .` fails). If installing pyenv, this\n must be installed _first_.\n\n ```\n\n - On Ubuntu: `sudo apt-get update` and then\n `sudo apt-get install -y bash findutils grep xxd git xxhash rsync expect jq unzip curl git-core gcc make zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev libssl-dev libffi-dev`.\n\n - Requires `pyenv`, or an exact matching version of python as in\n [./.python-version](https://github.com/realazthat/snipinator/blob/v3.1.2/.python-version) (which is currently\n `3.8.0`).\n - act (to run the GH Action locally):\n - Requires nodejs.\n - Requires Go.\n - docker.\n - Generate animation:\n - docker\n - docker (for building the docker image).\n\n### Commit Process\n\n1. (Optionally) Fork the `develop` branch.\n2. Stage your files: `git add path/to/file.py`.\n3. `bash ./scripts/pre.sh`, this will format, lint, and test the code.\n4. `git status` check if anything changed (generated\n [./README.md](https://github.com/realazthat/snipinator/blob/v3.1.2/README.md) for example), if so, `git add` the\n changes, and go back to the previous step.\n5. `git commit -m \"...\"`.\n6. Make a PR to `develop` (or push to develop if you have the rights).\n\n## \ud83d\udd04\ud83d\ude80 Release Process\n\nThese instructions are for maintainers of the project.\n\n1. In the `develop` branch, run `bash ./scripts/pre.sh` to ensure\n everything is in order.\n2. In the `develop` branch, bump the version in\n [./pyproject.toml](https://github.com/realazthat/snipinator/blob/v3.1.2/pyproject.toml), following semantic versioning\n principles. Also modify the `last_release` and `last_stable_release` in the\n `[tool.snipinator-project-metadata]` table as appropriate. Run\n `bash ./scripts/pre.sh` to ensure everything is in order.\n3. In the `develop` branch, commit these changes with a message like\n `\"Prepare release X.Y.Z\"`. (See the contributions section\n [above](#commit-process)).\n4. Merge the `develop` branch into the `master` branch:\n `git checkout master && git merge develop --no-ff`.\n5. `master` branch: Tag the release: Create a git tag for the release with\n `git tag -a vX.Y.Z -m \"Version X.Y.Z\"`.\n6. Publish to PyPI: Publish the release to PyPI with\n `bash ./scripts/deploy-to-pypi.sh`.\n7. Push to GitHub: Push the commit and tags to GitHub with\n `git push && git push --tags`.\n8. The `--no-ff` option adds a commit to the master branch for the merge, so\n refork the develop branch from the master branch:\n `git checkout develop && git merge master`.\n9. Push the develop branch to GitHub: `git push origin develop`.\n\n[1]: https://raw.githubusercontent.com/realazthat/snipinator/v3.1.2/.github/logo-exported.svg\n[2]: https://github.com/realazthat/snipinator\n[3]: https://img.shields.io/badge/Audience-Developers-0A1E1E?style=plastic&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJsdWNpZGUgbHVjaWRlLXVzZXJzIj48cGF0aCBkPSJNMTYgMjF2LTJhNCA0IDAgMCAwLTQtNEg2YTQgNCAwIDAgMC00IDR2MiIvPjxjaXJjbGUgY3g9IjkiIGN5PSI3IiByPSI0Ii8+PHBhdGggZD0iTTIyIDIxdi0yYTQgNCAwIDAgMC0zLTMuODciLz48cGF0aCBkPSJNMTYgMy4xM2E0IDQgMCAwIDEgMCA3Ljc1Ii8+PC9zdmc+\n[4]: https://img.shields.io/badge/Platform-Linux-0A1E1E?style=plastic&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIyNCIgaGVpZ2h0PSIyNCIgdmlld0JveD0iMCAwIDI0IDI0IiBmaWxsPSJub25lIiBzdHJva2U9ImN1cnJlbnRDb2xvciIgc3Ryb2tlLXdpZHRoPSIyIiBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGNsYXNzPSJsdWNpZGUgbHVjaWRlLWxhcHRvcC1taW5pbWFsIj48cmVjdCB3aWR0aD0iMTgiIGhlaWdodD0iMTIiIHg9IjMiIHk9IjQiIHJ4PSIyIiByeT0iMiIvPjxsaW5lIHgxPSIyIiB4Mj0iMjIiIHkxPSIyMCIgeTI9IjIwIi8+PC9zdmc+\n[5]: https://img.shields.io/github/languages/top/realazthat/snipinator.svg?cacheSeconds=28800&style=plastic&color=0A1E1E\n[6]: https://img.shields.io/github/license/realazthat/snipinator?style=plastic&color=0A1E1E\n[7]: https://github.com/realazthat/snipinator/blob/v3.1.2/LICENSE.md\n[8]: https://img.shields.io/pypi/v/snipinator?style=plastic&color=0A1E1E\n[9]: https://pypi.org/project/snipinator/\n[10]: https://img.shields.io/pypi/pyversions/snipinator?style=plastic&color=0A1E1E\n[11]: https://github.com/realazthat/snipinator/tree/master\n[12]: https://img.shields.io/github/actions/workflow/status/realazthat/snipinator/build-and-test.yml?branch=master&style=plastic\n[13]: https://github.com/realazthat/snipinator/actions/workflows/build-and-test.yml\n[14]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/master?style=plastic\n[15]: https://github.com/realazthat/snipinator/compare/v3.1.2...master\n[16]: https://img.shields.io/github/last-commit/realazthat/snipinator/master?style=plastic\n[17]: https://github.com/realazthat/snipinator/commits/master\n[18]: https://github.com/realazthat/snipinator/tree/develop\n[19]: https://img.shields.io/github/actions/workflow/status/realazthat/snipinator/build-and-test.yml?branch=develop&style=plastic\n[20]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/develop?style=plastic\n[21]: https://github.com/realazthat/snipinator/compare/v3.1.2...develop\n[22]: https://img.shields.io/github/commits-since/realazthat/snipinator/v3.1.2/develop?style=plastic\n[23]: https://github.com/realazthat/snipinator/compare/v3.1.2...develop\n[24]: https://img.shields.io/github/last-commit/realazthat/snipinator/develop?style=plastic\n[25]: https://github.com/realazthat/snipinator/commits/develop\n[26]: https://github.com/realazthat/snipinator\n[27]: https://github.com/realazthat/snipinator/blob/376cb1d83124ad00ce7c2a887d713ac2a85b9258/README.md?plain=1\n[28]: https://github.com/realazthat/snipinator/blob/376cb1d83124ad00ce7c2a887d713ac2a85b9258/scripts/generate-readme.sh#L20\n[29]: https://github.com/realazthat/mdremotifier\n[30]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/README.md.jinja2\n[31]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/README.md?plain=1\n[32]: https://github.com/realazthat/mdremotifier/blob/b1ea58ebb4f1b223719c6103d67ed5d588e66181/scripts/generate-readme.sh#L20\n[33]: https://github.com/realazthat/changeguard\n[34]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/README.md.jinja2\n[35]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/README.md?plain=1\n[36]: https://github.com/realazthat/changeguard/blob/909d21314de67f66ea05c6603a6df1d675d86697/scripts/generate-readme.sh#L20\n[37]: https://github.com/realazthat/excalidraw-brute-export-cli\n[38]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/README.md.jinja2\n[39]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/README.md?plain=1\n[40]: https://github.com/realazthat/excalidraw-brute-export-cli/blob/4b689ab75cfdec71e5788b3194f8736246e7544f/scripts/generate-readme.sh#L65\n[41]: https://github.com/realazthat/comfy-catapult\n[42]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/README.md.jinja2\n[43]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/README.md?plain=1\n[44]: https://github.com/realazthat/comfy-catapult/blob/ff353d48b25fa7b9c35fa11b31d5f2b3039c41c8/scripts/gen-readme.sh#L17\n[45]: https://github.com/realazthat/comfylowda\n[46]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/README.md.jinja2\n[47]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/README.md?plain=1\n[48]: https://github.com/realazthat/comfylowda/blob/e01a32c38107aa0b89ccea21c4678d193a186a78/scripts/gen-readme.sh#L19\n[49]: https://ghcr.io/realazthat/snipinator\n[50]: https://github.com/mdx-js/mdx\n[51]: https://github.com/fletcher/MultiMarkdown-6\n[52]: https://github.com/gajus/gitdown\n[53]: https://github.com/gpoore/codebraid\n[54]: https://github.com/amyreese/markdown-pp \"Archived\"\n[55]: https://github.com/zakhenry/embedme\n[56]: https://github.com/DCsunset/pandoc-include\n[57]: https://github.com/BurdetteLamar/markdown_helper\n[58]: https://github.com/SimonCropp/MarkdownSnippets\n[59]: https://github.com/endocode/snippetextractor\n[60]: https://github.com/polywrap/doc-snippets\n[61]: https://github.com/hxtmike/markdown_include\n[62]: https://github.com/JulianCataldo/remark-embed\n[63]: https://github.com/xrd/oreilly-snippets\n[64]: https://github.com/DamonOehlman/injectcode\n[65]: https://github.com/electrovir/markdown-code-example-inserter\n[66]: https://github.com/andersfischernielsen/Simple-Embedded-Markdown-Code-Snippets\n[67]: https://github.com/ildar-shaimordanov/git-markdown-snippet\n[68]: https://github.com/marc-bouvier-graveyard/baldir_markdown\n[69]: https://github.com/facelessuser/pymdown-extensions\n[70]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/\n[71]: https://github.com/dineshsonachalam/markdown-autodocs\n[72]: https://github.com/sethen/markdown-include \"CLI but requires that you make a json file with various optiosn to produce the output\"\n[73]: https://github.com/cmacmackin/markdown-include\n[74]: https://github.com/tokusumi/markdown-embed-code\n[75]: https://github.com/sammndhr/gridsome-remark-embed-snippet\n[76]: https://gridsome.org/\n[77]: https://github.com/NativeScript/markdown-snippet-injector\n[78]: https://github.com/fossunited/markdown-macros\n[79]: https://github.com/fuxingloh/remark-code-import-replace\n[80]: https://github.com/teyc/markdown-snippet\n[81]: https://github.com/szkiba/mdcode \"Extracts code blocks from README and produces tests; a similar approach, but quite different\"\n[82]: https://github.com/devincornell/pymddoc\n[83]: https://github.com/shiftkey/scribble\n[84]: https://github.com/shiftkey/scribble/blob/master/docs/features/code-snippets.md\n[85]: https://github.com/calebpeterson/jest-transformer-test-md\n[86]: https://github.com/tjstankus/commitate \"Missing usage example\"\n[87]: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-a-permanent-link-to-a-code-snippet\n[88]: https://github.com/javierfernandes/markdown-exercises \"This doesn't embed files, rather allows markdown code sections to be tested, no usage example\"\n[89]: https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-embed-snippet\n[90]: https://github.com/gatsbyjs/gatsby\n[91]: https://github.com/ARMmbed/snippet \"Unclear from documentation on how to embed the code into the template\"\n[92]: https://github.com/ARMmbed/snippet/blob/master/USAGE.md\n[93]: https://github.com/drewavis/markdowninclude\n[94]: https://github.com/romnn/embedme \"Documentation is lacking\"\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Azriel Fasten. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice (including the next paragraph) shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Python code snippets for markdown files, e.g READMEs, from actual (testable) code.",
"version": "3.1.2",
"project_urls": {
"Documentation": "https://github.com/realazthat/snipinator",
"Homepage": "https://github.com/realazthat/snipinator",
"Repository": "https://github.com/realazthat/snipinator"
},
"split_keywords": [
"github",
" testing",
" markdown",
" readme",
" snippets",
" documentation",
" jinja2",
" templates",
" preprocessor",
" documentation-tool",
" include",
" readme-template",
" readme-md",
" dynamic-documentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c93fb42171692520846fc6750b8d19c217789372b23fe88f2b227c1818b3f3d",
"md5": "c8523baa8f20e24e151a4a01b420fc1a",
"sha256": "838ec02c2c5d7b2128c813d7d37e914db7f5a7c368fc1dff1e1a6cbee73eb0bb"
},
"downloads": -1,
"filename": "snipinator-3.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8523baa8f20e24e151a4a01b420fc1a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 35865,
"upload_time": "2024-08-09T06:08:43",
"upload_time_iso_8601": "2024-08-09T06:08:43.422882Z",
"url": "https://files.pythonhosted.org/packages/2c/93/fb42171692520846fc6750b8d19c217789372b23fe88f2b227c1818b3f3d/snipinator-3.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0dd5a973753e0a5f70af5bbe18ece4afebe2261f3bd643f4970567fd466c310d",
"md5": "73107f884437b0bf30025dff8cc6bc96",
"sha256": "7666f3ccb0e7b4fbde383d296499d125139f2235bf1ec1ecb772de1358ffcd5d"
},
"downloads": -1,
"filename": "snipinator-3.1.2.tar.gz",
"has_sig": false,
"md5_digest": "73107f884437b0bf30025dff8cc6bc96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 72440,
"upload_time": "2024-08-09T06:08:45",
"upload_time_iso_8601": "2024-08-09T06:08:45.478260Z",
"url": "https://files.pythonhosted.org/packages/0d/d5/a973753e0a5f70af5bbe18ece4afebe2261f3bd643f4970567fd466c310d/snipinator-3.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-09 06:08:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "realazthat",
"github_project": "snipinator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "snipinator"
}
