Evaluate shell command or python code in sphinx and myst.
docs/conf.py
extensions = [ "sphinxcontrib.eval", ]Or
extensions = [ "myst_parser", "sphinxcontrib.eval", # must be after myst_parser ]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/htmlResult:
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 └── testsAnd you want to run scripts/*.sh, you need cd .. firstly from docs to . else you have to run ../scripts/*.sh.
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.
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.py 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 .. scripts/generate-todo.md.pl src/**/* ```Where scripts/generate-todo.md.pl searches all TODOs in code then convert them to correct hyperlinks.
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.