-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
29 changed files
with
97 additions
and
953 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,223 +0,0 @@ | ||
| # sphinxcontrib-eval | ||
|
|
||
| [](https://results.pre-commit.ci/latest/github/sphinx-contrib/eval/main) | ||
| [](https://github.com/sphinx-contrib/eval/actions) | ||
| [](https://codecov.io/gh/sphinx-contrib/eval) | ||
| [](https://sphinxcontrib-eval.readthedocs.io) | ||
|
|
||
| [](https://github.com/sphinx-contrib/eval/releases) | ||
| [](https://github.com/sphinx-contrib/eval/releases/latest) | ||
| [](https://github.com/sphinx-contrib/eval/issues) | ||
| [](https://github.com/sphinx-contrib/eval/issues?q=is%3Aissue+is%3Aclosed) | ||
| [](https://github.com/sphinx-contrib/eval/pulls) | ||
| [](https://github.com/sphinx-contrib/eval/pulls?q=is%3Apr+is%3Aclosed) | ||
| [](https://github.com/sphinx-contrib/eval/discussions) | ||
| [](https://github.com/sphinx-contrib/eval/milestones) | ||
| [](https://github.com/sphinx-contrib/eval/network/members) | ||
| [](https://github.com/sphinx-contrib/eval/stargazers) | ||
| [](https://github.com/sphinx-contrib/eval/watchers) | ||
| [](https://github.com/sphinx-contrib/eval/graphs/contributors) | ||
| [](https://github.com/sphinx-contrib/eval/graphs/commit-activity) | ||
| [](https://github.com/sphinx-contrib/eval/commits) | ||
| [](https://github.com/sphinx-contrib/eval/releases/latest) | ||
|
|
||
| [](https://github.com/sphinx-contrib/eval/blob/main/LICENSE) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
| [](https://github.com/sphinx-contrib/eval) | ||
|
|
||
| [](https://pypi.org/project/sphinxcontrib-eval/#description) | ||
| [](https://pypi.org/project/sphinxcontrib-eval/#history) | ||
| [](https://pypi.org/project/sphinxcontrib-eval/#files) | ||
| [](https://pypi.org/project/sphinxcontrib-eval/#files) | ||
| [](https://pypi.org/project/sphinxcontrib-eval/#files) | ||
| [](https://pypi.org/project/sphinxcontrib-eval/#files) | ||
|
|
||
| Evaluate shell command or python code in sphinx and myst. | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Enable | ||
|
|
||
| `docs/conf.py` | ||
|
|
||
| ```python | ||
| extensions = [ | ||
| "sphinxcontrib.eval", | ||
| ] | ||
| ``` | ||
|
|
||
| Or | ||
|
|
||
| ```python | ||
| extensions = [ | ||
| "myst_parser", | ||
| "sphinxcontrib.eval", # must be after myst_parser | ||
| ] | ||
| ``` | ||
|
|
||
| ### Demonstration | ||
|
|
||
| For myst: | ||
|
|
||
| ````markdown | ||
| ```{eval-sh} | ||
| echo My OS is $OSTYPE. | ||
| ``` | ||
| ```` | ||
|
|
||
| For rst: | ||
|
|
||
| ```rst | ||
| .. eval-sh:: | ||
| echo My OS is $OSTYPE. | ||
| ``` | ||
|
|
||
| Then build: | ||
|
|
||
| ```sh | ||
| sphinx-build docs docs/_build/html | ||
| ``` | ||
|
|
||
| Result: | ||
|
|
||
| ```text | ||
| 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 | ||
|
|
||
| ```console | ||
| $ 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](https://github.com/Freed-Wu/translate-shell/tree/main/docs/api/translate_shell.md) | ||
|
|
||
| Before: | ||
|
|
||
| ````markdown | ||
| # API of Translate Shell | ||
|
|
||
| ```{eval-rst} | ||
| .. automodule:: translate_shell | ||
| :members: | ||
| .. automodule:: translate_shell.__main__ | ||
| :members: | ||
| ... (More) | ||
| ``` | ||
| ```` | ||
|
|
||
| Now | ||
|
|
||
| `````markdown | ||
| # API of Translate Shell | ||
|
|
||
| ````{eval-rst} | ||
| ```{eval-sh} | ||
| cd .. | ||
| scripts/generate-api.md.pl src/*/*.py | ||
| ``` | ||
| ```` | ||
| ````` | ||
|
|
||
| Where | ||
| [`scripts/generate-api.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-api.md.pl) | ||
| replaces all `src/translate_shell/XXX.py`s to | ||
|
|
||
| ```rst | ||
| .. automodule:: translate_shell.XXX | ||
| :members: | ||
| ``` | ||
|
|
||
| #### [Generate TODO Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/misc/todo.md) | ||
|
|
||
| Before: | ||
|
|
||
| ```markdown | ||
| # 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`) | ||
|
|
||
| ````markdown | ||
| # TODO | ||
|
|
||
| ```{eval-bash} | ||
| cd .. | ||
| shopt -s globstar | ||
| scripts/generate-todo.md.pl src/**/*.py | ||
| ``` | ||
| ```` | ||
|
|
||
| Where | ||
| [`scripts/generate-todo.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-todo.md.pl) | ||
| searches all `TODO`s in code then convert them to correct hyperlinks. | ||
|
|
||
| #### [Generate Requirements Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md) | ||
|
|
||
| Before: | ||
|
|
||
| ```markdown | ||
| # Requirements | ||
|
|
||
| ## completion | ||
|
|
||
| Generate shell completion scripts. | ||
|
|
||
| - [shtab](https://pypi.org/project/shtab) | ||
|
|
||
| ... | ||
| ``` | ||
|
|
||
| Now | ||
|
|
||
| ````markdown | ||
| # Requirements | ||
|
|
||
| ```{eval-sh} | ||
| cd .. | ||
| generate-requirements.md.pl | ||
| ``` | ||
| ```` | ||
|
|
||
| Where | ||
| [`scripts/generate-requirements.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-requirements.md.pl) | ||
| searches all `requirements/*.txt`s and `requirements/completion.txt` is: | ||
|
|
||
| ```unixconfig | ||
| #!/usr/bin/env -S pip install -r | ||
| # Generate shell completion scripts. | ||
| shtab | ||
| ``` | ||
|
|
||
| See [document](https://sphinxcontrib-eval.readthedocs.io) to know more. | ||
This file was deleted.
Oops, something went wrong.
Oops, something went wrong.