| Name | sphinxcontrib-eval JSON |
| Version |
0.0.3
JSON |
| download |
| home_page | |
| Summary | Evaluate shell command or python code in sphinx and myst |
| upload_time | 2023-01-12 10:00:26 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.9 |
| license | GPL v3 |
| keywords |
sphinx
myst
eval
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# sphinxcontrib-eval
[](https://results.pre-commit.ci/latest/github/Freed-Wu/sphinxcontrib-eval/main)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/actions)
[](https://codecov.io/gh/Freed-Wu/sphinxcontrib-eval)
[](https://sphinxcontrib-eval.readthedocs.io)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases/latest)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/issues)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/issues?q=is%3Aissue+is%3Aclosed)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/pulls)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/pulls?q=is%3Apr+is%3Aclosed)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/discussions)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/milestones)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/network/members)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/stargazers)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/watchers)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/graphs/contributors)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/graphs/commit-activity)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/commits)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases/latest)
[](https://github.com/Freed-Wu/sphinxcontrib-eval/blob/main/LICENSE)
[](https://github.com/Freed-Wu/sphinxcontrib-eval)
[](https://github.com/Freed-Wu/sphinxcontrib-eval)
[](https://github.com/Freed-Wu/sphinxcontrib-eval)
[](https://github.com/Freed-Wu/sphinxcontrib-eval)
[](https://github.com/Freed-Wu/sphinxcontrib-eval)
[](https://github.com/Freed-Wu/sphinxcontrib-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)
is a script which replace all `src/translate_shell/XXX.py` 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 ..
scripts/generate-todo.md.pl src/**/*
```
````
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.
Raw data
{
"_id": null,
"home_page": "",
"name": "sphinxcontrib-eval",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "sphinx,myst,eval",
"author": "",
"author_email": "Wu Zhenyu <wuzhenyu@ustc.edu>",
"download_url": "https://files.pythonhosted.org/packages/74/1a/d4a57147771faa8e1466ca56de0d95621575af3ac4768c9e14c3198ed554/sphinxcontrib-eval-0.0.3.tar.gz",
"platform": null,
"description": "# sphinxcontrib-eval\n\n[](https://results.pre-commit.ci/latest/github/Freed-Wu/sphinxcontrib-eval/main)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/actions)\n[](https://codecov.io/gh/Freed-Wu/sphinxcontrib-eval)\n[](https://sphinxcontrib-eval.readthedocs.io)\n\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases/latest)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/issues)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/issues?q=is%3Aissue+is%3Aclosed)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/pulls)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/pulls?q=is%3Apr+is%3Aclosed)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/discussions)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/milestones)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/network/members)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/stargazers)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/watchers)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/graphs/contributors)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/graphs/commit-activity)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/commits)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/releases/latest)\n\n[](https://github.com/Freed-Wu/sphinxcontrib-eval/blob/main/LICENSE)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n[](https://github.com/Freed-Wu/sphinxcontrib-eval)\n\n[](https://pypi.org/project/sphinxcontrib-eval/#description)\n[](https://pypi.org/project/sphinxcontrib-eval/#history)\n[](https://pypi.org/project/sphinxcontrib-eval/#files)\n[](https://pypi.org/project/sphinxcontrib-eval/#files)\n[](https://pypi.org/project/sphinxcontrib-eval/#files)\n[](https://pypi.org/project/sphinxcontrib-eval/#files)\n\nEvaluate shell command or python code in sphinx and myst.\n\n## Usage\n\n### Enable\n\n`docs/conf.py`\n\n```python\nextensions = [\n \"sphinxcontrib.eval\",\n]\n```\n\nOr\n\n```python\nextensions = [\n \"myst_parser\",\n \"sphinxcontrib.eval\", # must be after myst_parser\n]\n```\n\n### Demonstration\n\nFor myst:\n\n````markdown\n```{eval-sh}\necho My OS is $OSTYPE.\n```\n````\n\nFor rst:\n\n```rst\n.. eval-sh::\n echo My OS is $OSTYPE.\n\n```\n\nThen build:\n\n```sh\nsphinx-build docs docs/_build/html\n```\n\nResult:\n\n```text\nMy OS is linux-gnu.\n```\n\n**NOTE:** the current working directory depends on you. That is, if you run\n`cd docs && sphinx-build . _build/html && cd -`, CWD will be `docs`, which is\nthe default setting of <https://readthedocs.org>. So if your code structure is\nlike\n\n```console\n$ tree --level 1\n\uf115 .\n\u251c\u2500\u2500 \uf115 docs\n\u251c\u2500\u2500 \uf115 scripts\n\u251c\u2500\u2500 \uf115 src\n\u2514\u2500\u2500 \uf115 tests\n```\n\nAnd you want to run `scripts/*.sh`, you need `cd ..` firstly from `docs` to\n`.` else you have to run `../scripts/*.sh`.\n\n### Advanced Usages\n\nAll of the following examples are myst. The corresponding examples of rst are\nsimilar. Click the hyperlinks of the titles and scripts to see the actual\nexamples.\n\n#### [Generate API Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/api/translate_shell.md)\n\nBefore:\n\n````markdown\n# API of Translate Shell\n\n```{eval-rst}\n.. automodule:: translate_shell\n :members:\n.. automodule:: translate_shell.__main__\n :members:\n... (More)\n```\n````\n\nNow\n\n`````markdown\n# API of Translate Shell\n\n````{eval-rst}\n```{eval-sh}\ncd ..\nscripts/generate-api.md.pl src/*/*.py\n```\n````\n`````\n\nWhere\n[`scripts/generate-api.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-api.md.pl)\nis a script which replace all `src/translate_shell/XXX.py` to\n\n```rst\n.. automodule:: translate_shell.XXX\n :members:\n```\n\n#### [Generate TODO Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/misc/todo.md)\n\nBefore:\n\n```markdown\n# TODO\n\n- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L4>\n more stardicts.\n- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L5>\n Create different subclasses for different dict to get phonetic, explains\n- <https://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/ui/repl.py#L33>\n make the last line gray like ptpython\n- ...\n```\n\nNow: (notice `eval-bash` because readthedocs uses dash as their default `$SHELL`)\n\n````markdown\n# TODO\n\n```{eval-bash}\ncd ..\nscripts/generate-todo.md.pl src/**/*\n```\n````\n\nWhere\n[`scripts/generate-todo.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-todo.md.pl)\nsearches all `TODO`s in code then convert them to correct hyperlinks.\n\n#### [Generate Requirements Document](https://github.com/Freed-Wu/translate-shell/tree/main/docs/resources/requirements.md)\n\nBefore:\n\n```markdown\n# Requirements\n\n## completion\n\nGenerate shell completion scripts.\n\n- [shtab](https://pypi.org/project/shtab)\n\n...\n```\n\nNow\n\n````markdown\n# Requirements\n\n```{eval-sh}\ncd ..\ngenerate-requirements.md.pl\n```\n````\n\nWhere\n[`scripts/generate-requirements.md.pl`](https://github.com/Freed-Wu/translate-shell/blob/main/scripts/generate-requirements.md.pl)\nsearches all `requirements/*.txt`s and `requirements/completion.txt` is:\n\n```unixconfig\n#!/usr/bin/env -S pip install -r\n# Generate shell completion scripts.\n\nshtab\n```\n\nSee [document](https://sphinxcontrib-eval.readthedocs.io) to know more.\n",
"bugtrack_url": null,
"license": "GPL v3",
"summary": "Evaluate shell command or python code in sphinx and myst",
"version": "0.0.3",
"split_keywords": [
"sphinx",
"myst",
"eval"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ea8d1d9fda5bd281aaf17163eb64f6bac4eff924b5ac54b398d35ae0d4796ede",
"md5": "a5c0d53d87ce14b0f3a2ce6c79a9e90c",
"sha256": "c9fb71dc1901039378b0ee5a12ac74c2140a458cd2ac7a5b18ad8a344caf5505"
},
"downloads": -1,
"filename": "sphinxcontrib_eval-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5c0d53d87ce14b0f3a2ce6c79a9e90c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 18584,
"upload_time": "2023-01-12T10:00:24",
"upload_time_iso_8601": "2023-01-12T10:00:24.995685Z",
"url": "https://files.pythonhosted.org/packages/ea/8d/1d9fda5bd281aaf17163eb64f6bac4eff924b5ac54b398d35ae0d4796ede/sphinxcontrib_eval-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "741ad4a57147771faa8e1466ca56de0d95621575af3ac4768c9e14c3198ed554",
"md5": "53438fceda7190c418058b207a16daac",
"sha256": "e184b0216ee5d07711dbdde5d79a71313e92010d363e318f63125dce37a19129"
},
"downloads": -1,
"filename": "sphinxcontrib-eval-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "53438fceda7190c418058b207a16daac",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 29234,
"upload_time": "2023-01-12T10:00:26",
"upload_time_iso_8601": "2023-01-12T10:00:26.591238Z",
"url": "https://files.pythonhosted.org/packages/74/1a/d4a57147771faa8e1466ca56de0d95621575af3ac4768c9e14c3198ed554/sphinxcontrib-eval-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-12 10:00:26",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "sphinxcontrib-eval"
}
