https://github.com/sphinx-contrib/eval
Evaluate shell command or python code in sphinx and myst. maintainers: @Freed-Wu
https://github.com/sphinx-contrib/eval
eval python shell sphinx
Last synced: 2 months ago
JSON representation
Evaluate shell command or python code in sphinx and myst. maintainers: @Freed-Wu
- Host: GitHub
- URL: https://github.com/sphinx-contrib/eval
- Owner: sphinx-contrib
- License: gpl-3.0
- Created: 2022-12-10T01:58:00.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-02-19T07:18:08.000Z (about 1 year ago)
- Last Synced: 2025-02-11T23:50:04.697Z (3 months ago)
- Topics: eval, python, shell, sphinx
- Language: Python
- Homepage: https://sphinxcontrib-eval.readthedocs.io/
- Size: 62.5 KB
- Stars: 0
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
README
# sphinxcontrib-eval
[](https://results.pre-commit.ci/latest/github/sphinx-contrib/eval/main)
[](https://github.com/sphinx-contrib/eval/actions)
[](https://codecov.io/gh/sphinx-contrib/eval)
[](https://sphinxcontrib-eval.readthedocs.io)
[](https://github.com/sphinx-contrib/eval/releases)
[](https://github.com/sphinx-contrib/eval/releases/latest)
[](https://github.com/sphinx-contrib/eval/issues)
[](https://github.com/sphinx-contrib/eval/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/sphinx-contrib/eval/pulls)
[](https://github.com/sphinx-contrib/eval/pulls?q=is%3Apr+is%3Aclosed)
[](https://github.com/sphinx-contrib/eval/discussions)
[](https://github.com/sphinx-contrib/eval/milestones)
[](https://github.com/sphinx-contrib/eval/network/members)
[](https://github.com/sphinx-contrib/eval/stargazers)
[](https://github.com/sphinx-contrib/eval/watchers)
[](https://github.com/sphinx-contrib/eval/graphs/contributors)
[](https://github.com/sphinx-contrib/eval/graphs/commit-activity)
[](https://github.com/sphinx-contrib/eval/commits)
[](https://github.com/sphinx-contrib/eval/releases/latest)
[](https://github.com/sphinx-contrib/eval/blob/main/LICENSE)
[](https://github.com/sphinx-contrib/eval)
[](https://github.com/sphinx-contrib/eval)
[](https://github.com/sphinx-contrib/eval)
[](https://github.com/sphinx-contrib/eval)
[](https://github.com/sphinx-contrib/eval)
[](https://github.com/sphinx-contrib/eval)
[](https://pypi.org/project/sphinxcontrib-eval/#description)
[](https://pypi.org/project/sphinxcontrib-eval/#history)
[](https://pypi.org/project/sphinxcontrib-eval/#files)
[](https://pypi.org/project/sphinxcontrib-eval/#files)
[](https://pypi.org/project/sphinxcontrib-eval/#files)
[](https://pypi.org/project/sphinxcontrib-eval/#files)
Evaluate shell command or python code in sphinx and myst.
## Install
See [here](https://sphinxcontrib-eval.readthedocs.io/en/latest/resources/install.html).
## Usage
### Enable
`docs/conf.py`
```python
extensions = [
"sphinxcontrib.eval",
]
```
Or
```python
extensions = [
"myst_parser",
"sphinxcontrib.eval", # must be after myst_parser
]
```
### Demonstration
For myst:
````markdown
```{eval-sh}
echo My OS is $OSTYPE.
```
````
For rst:
```rst
.. eval-sh::
echo My OS is $OSTYPE.
```
Then build:
```sh
sphinx-build docs docs/_build/html
```
Result:
```text
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 . So if your code structure is
like
```console
$ 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](https://github.com/Freed-Wu/translate-shell/tree/main/docs/api/translate_shell.md)
**Note**: A more "sphinx" solution is
[sphinxcontrib-autofile](https://github.com/sphinx-contrib/autofile).
Before:
````markdown
# API of Translate Shell
```{eval-rst}
.. automodule:: translate_shell
:members:
.. automodule:: translate_shell.__main__
:members:
... (More)
```
````
Now
`````markdown
# API of Translate Shell
````{eval-rst}
```{eval-sh}
cd ..
scripts/generate-api.md.pl src/*/*.py
```
````
`````
Where
[`scripts/generate-api.md.pl`](https://github.com/sphinx-contrib/eval/blob/main/scripts/generate-api.md.pl)
replaces all `src/translate_shell/XXX.py`s to
```rst
.. automodule:: translate_shell.XXX
:members:
```
#### [Generate TODO Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/misc/todo.md)
Before:
```markdown
# TODO
-
more stardicts.
-
Create different subclasses for different dict to get phonetic, explains
-
make the last line gray like ptpython
- ...
```
Now: (notice `eval-bash` because readthedocs uses dash as their default `$SHELL`)
````markdown
# TODO
```{eval-bash}
cd ..
shopt -s globstar
scripts/generate-todo.md.pl src/**/*.py
```
````
Where
[`scripts/generate-todo.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-todo.md.pl)
searches all `TODO`s in code then convert them to correct hyperlinks.
#### [Generate Requirements Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md)
**Note**: A more "sphinx" solution is
[sphinxcontrib-requirements-txt](https://github.com/sphinx-contrib/requirements-txt).
Before:
```markdown
# Requirements
## completion
Generate shell completion scripts.
- [shtab](https://pypi.org/project/shtab)
...
```
Now
````markdown
# Requirements
```{eval-sh}
cd ..
generate-requirements.md.pl
```
````
Where
[`scripts/generate-requirements.md.pl`](https://github.com/sphinx-contrib/eval/blob/main/scripts/generate-requirements.md.pl)
searches all `requirements/*.txt`s and `requirements/completion.txt` is:
```unixconfig
#!/usr/bin/env -S pip install -r
# Generate shell completion scripts.
shtab
```
See [document](https://sphinxcontrib-eval.readthedocs.io) to know more.