sphinxcontrib-eval 0.0.1

Evaluate shell command or python code in sphinx and myst

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 the following code is myst. The corresponding rst is similar. 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}
scripts/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/X/Y/Z.py to

.. automodule:: translate_shell.X.Y.Z`
    :members:

#!/usr/bin/env bash
# shellcheck disable=SC2086
find src/sphinxcontrib/eval/$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}
scripts/generate-todo.md.sh
```

Where the script searches all TODOs in code then convert them to correct hyperlinks.

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'

Generate Requirement Document

Before:

# Requirements

## completion

Generate shell completion scripts.

- [shtab](https://pypi.org/project/shtab)

...

Now

# Requirements

```{eval-sh}
scripts/generate-requirements.md.sh
```

Where

#!/usr/bin/env bash
for file in requirements.txt 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:

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

shtab

See document to know more.