sphinxcontrib-eval

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.

Generate API Document

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:

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 ..
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.

Generate Requirements Document

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.