Evaluate shell command or python code in sphinx and myst
Project description
sphinxcontrib-eval
Evaluate shell command or python code in sphinx and myst.
Usage
Enable
docs/conf.py
extensions = [
"sphinxcontrib.eval",
]
Or
extensions = [
"myst_parser",
"sphinxcontrib.eval", # must be after myst_parser
]
Demonstration
For myst:
```{eval-sh}
echo My OS is $OSTYPE.
```
For rst:
.. eval-sh::
echo My OS is $OSTYPE.
Then build:
sphinx-build docs docs/_build/html
Result:
My OS is linux-gnu.
Advanced Usages
All of the following examples are myst. The corresponding examples of rst are
similar. Remember to add scripts
to your $PATH
in docs/conf.py
.
Click the hyperlink of title to see the actual example.
Generate API Document
Before:
# API of Translate Shell
```{eval-rst}
.. automodule:: translate_shell
:members:
.. automodule:: translate_shell.__main__
:members:
... (More)
```
Now
# API of Translate Shell
````{eval-rst}
```{eval-sh}
generate-api.md.sh '' -maxdepth 1
```
````
Where scripts/generate-api.md.sh
is a script which search all python file and
replace them from src/translate_shell/XXX.py
to
.. automodule:: translate_shell.XXX
:members:
#!/usr/bin/env bash
# shellcheck disable=SC2086
cd "$(dirname "$(dirname "$0")")" || exit 1
find src/translate_shell/$1 $2 $3 -name '*.py' |
perl -pe's=src/=.. automodule:: =g;
s=\.py$=\n :members:=g;s=/__init__==g;s=/=.=g'
Generate TODO Document
Before:
# TODO
- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L4>
more stardicts.
- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L5>
Create different subclasses for different dict to get phonetic, explains
- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/ui/repl.py#L33>
make the last line gray like ptpython
- ...
Now:
# TODO
```{eval-sh}
generate-todo.md.sh
```
Where scripts/generate-todo.md.sh
searches all TODO
s in code then convert
them to correct hyperlinks.
#!/usr/bin/env bash
cd "$(dirname "$(dirname "$0")")" || exit 1
grep -RIn TODO: src | perl -pe's/:/#L/;s/:\s*#?\s*TODO:\s*/ /;
s=^=- https://github.com/Freed-Wu/tranlate-shell/tree/main/=g;
s=(https://\S+)=<\1>=g;s=^(- \S+)=\1\n=g'
Generate Requirements Document
Before:
# Requirements
## completion
Generate shell completion scripts.
- [shtab](https://pypi.org/project/shtab)
...
Now
# Requirements
```{eval-sh}
generate-requirements.md.sh
```
Where scripts/generate-requirements.md.sh
searches all requirements/*.txt
s:
#!/usr/bin/env bash
cd "$(dirname "$(dirname "$0")")" || exit 1
for file in requirements/*.txt ; do
filename="${file##*/}"
perl -pe's=^([^#\n]\S*)=- [\1](https://pypi.org/project/\1)=g;
s/^#\s*//g;s/^!.*/## '"${filename%%.txt}"'/g' < "$file"
done
And requirements/completion.txt
is:
#!/usr/bin/env -S pip install -r
# Generate shell completion scripts.
shtab
See document to know more.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for sphinxcontrib_eval-0.0.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | df65aa4dcfbb61fe03ef6effe0741018556846f6b683ae9085f2558fe63ebc03 |
|
MD5 | 43f5b3ce5d6beae713bc35d61733580b |
|
BLAKE2b-256 | 98721e3ca83fc88150cafc29b87ace6e35aabb4dc6d8ab7782ab1895dd289add |