sphinxcontrib-eval

在sphinx和myst中评估shell命令或Python代码。

使用方法

启用

docs/conf.py

extensions = [
    "sphinxcontrib.eval",
]

或

extensions = [
    "myst_parser",
    "sphinxcontrib.eval",  # must be after myst_parser
]

示例

对于myst

```{eval-sh}
echo My OS is $OSTYPE.
```

对于rst

.. eval-sh::
    echo My OS is $OSTYPE.

然后构建

sphinx-build docs docs/_build/html

结果

My OS is linux-gnu.

注意：当前工作目录取决于您。也就是说，如果您运行cd docs && sphinx-build . _build/html && cd -，CWD将是docs，这是https://readthedocs.org的默认设置。因此，如果您的代码结构如下

$ tree --level 1
 .
├──  docs
├──  scripts
├──  src
└──  tests

并且您想运行scripts/*.sh，您需要首先从docs切换到.，否则您必须运行../scripts/*.sh。

高级用法

以下所有示例都是myst。rst的相应示例类似。点击标题和脚本的超链接查看实际示例。

生成API文档

之前

# API of Translate Shell

```{eval-rst}
.. automodule:: translate_shell
    :members:
.. automodule:: translate_shell.__main__
    :members:
... (More)
```

现在

# API of Translate Shell

````{eval-rst}
```{eval-sh}
cd ..
scripts/generate-api.md.pl src/*/*.py
```
````

其中 scripts/generate-api.md.pl 是一个脚本，用于将所有 src/translate_shell/XXX.py 替换为

.. automodule:: translate_shell.XXX
    :members:

生成 TODO 文档

之前

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

现在：(注意 eval-bash，因为 ReadTheDocs 使用 dash 作为它们的默认 $SHELL )

# TODO

```{eval-bash}
cd ..
scripts/generate-todo.md.pl src/**/*
```

其中 scripts/generate-todo.md.pl 在代码中搜索所有 TODO，然后将它们转换为正确的超链接。

生成需求文档

之前

# Requirements

## completion

Generate shell completion scripts.

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

...

现在

# Requirements

```{eval-sh}
cd ..
generate-requirements.md.pl
```

其中 scripts/generate-requirements.md.pl 搜索所有 requirements/*.txt 和 requirements/completion.txt

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

shtab

查看 文档 了解更多信息。