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.
NOTE: the current working directory depends on you. That is, if you run
cd docs && sphinx-build . _build/html && cd -
, CWD will be docs
, which is
the default setting of https://readthedocs.org. So if your code structure is
like
$ tree --level 1
.
├── docs
├── scripts
├── src
└── tests
And you want to run scripts/*.sh
, you need cd ..
firstly from docs
to
.
else you have to run ../scripts/*.sh
.
Advanced Usages
All of the following examples are myst. The corresponding examples of rst are similar. Click the hyperlinks of the titles and scripts to see the actual examples.
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}
cd ..
scripts/generate-api.md.pl src/*/*.py
```
````
Where
scripts/generate-api.md.pl
is a script which replace all src/translate_shell/XXX.py
to
.. automodule:: translate_shell.XXX
:members:
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: (notice eval-bash
because readthedocs uses dash as their default $SHELL
)
# TODO
```{eval-bash}
cd ..
scripts/generate-todo.md.pl src/**/*
```
Where
scripts/generate-todo.md.pl
searches all TODO
s in code then convert them to correct hyperlinks.
Generate Requirements Document
Before:
# Requirements
## completion
Generate shell completion scripts.
- [shtab](https://pypi.org/project/shtab)
...
Now
# Requirements
```{eval-sh}
cd ..
generate-requirements.md.pl
```
Where
scripts/generate-requirements.md.pl
searches all requirements/*.txt
s 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.3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c9fb71dc1901039378b0ee5a12ac74c2140a458cd2ac7a5b18ad8a344caf5505 |
|
MD5 | a5c0d53d87ce14b0f3a2ce6c79a9e90c |
|
BLAKE2b-256 | ea8d1d9fda5bd281aaf17163eb64f6bac4eff924b5ac54b398d35ae0d4796ede |