/eval

Evaluate shell command or python code in sphinx and myst. maintainers: @Freed-Wu

Primary LanguagePythonGNU General Public License v3.0GPL-3.0

sphinxcontrib-eval

pre-commit.ci status github/workflow codecov readthedocs

github/downloads github/downloads/latest github/issues github/issues-closed github/issues-pr github/issues-pr-closed github/discussions github/milestones github/forks github/stars github/watchers github/contributors github/commit-activity github/last-commit github/release-date

github/license github/languages github/languages/top github/directory-file-count github/code-size github/repo-size github/v

pypi/status pypi/v pypi/downloads pypi/format pypi/implementation pypi/pyversions

Evaluate shell command or python code in sphinx and myst.

Install

See here.

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.

Note: A more "sphinx" solution is sphinxcontrib-autofile.

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 replaces all src/translate_shell/XXX.pys to

.. automodule:: translate_shell.XXX
    :members:

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 ..
shopt -s globstar
scripts/generate-todo.md.pl src/**/*.py
```

Where scripts/generate-todo.md.pl searches all TODOs in code then convert them to correct hyperlinks.

Note: A more "sphinx" solution is sphinxcontrib-requirements-txt.

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/*.txts and requirements/completion.txt is:

#!/usr/bin/env -S pip install -r
# Generate shell completion scripts.

shtab

See document to know more.