{"id":19931031,"url":"https://github.com/sphinx-contrib/eval","last_synced_at":"2026-04-30T02:36:14.930Z","repository":{"id":64532365,"uuid":"576486774","full_name":"sphinx-contrib/eval","owner":"sphinx-contrib","description":"Evaluate shell command or python code in sphinx and myst. maintainers: @Freed-Wu","archived":false,"fork":false,"pushed_at":"2026-04-06T21:47:22.000Z","size":52,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T23:24:13.614Z","etag":null,"topics":["eval","python","shell","sphinx"],"latest_commit_sha":null,"homepage":"https://sphinxcontrib-eval.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sphinx-contrib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":["https://user-images.githubusercontent.com/32936898/199681341-1c5cfa61-4411-4b67-b268-7cd87c5867bb.png","https://user-images.githubusercontent.com/32936898/199681363-1094a0be-85ca-49cf-a410-19b3d7965120.png","https://user-images.githubusercontent.com/32936898/199681368-c34c2be7-e0d8-43ea-8c2c-d3e865da6aeb.png"]}},"created_at":"2022-12-10T01:58:00.000Z","updated_at":"2023-10-15T01:18:29.000Z","dependencies_parsed_at":"2025-08-11T23:21:07.456Z","dependency_job_id":"fff0c784-0d36-4275-8b0a-b26168e4711e","html_url":"https://github.com/sphinx-contrib/eval","commit_stats":null,"previous_names":["freed-wu/sphinxcontrib-eval"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/sphinx-contrib/eval","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Feval","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Feval/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Feval/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Feval/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sphinx-contrib","download_url":"https://codeload.github.com/sphinx-contrib/eval/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sphinx-contrib%2Feval/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32452741,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eval","python","shell","sphinx"],"created_at":"2024-11-12T23:05:52.702Z","updated_at":"2026-04-30T02:36:14.916Z","avatar_url":"https://github.com/sphinx-contrib.png","language":"Python","funding_links":["https://user-images.githubusercontent.com/32936898/199681341-1c5cfa61-4411-4b67-b268-7cd87c5867bb.png","https://user-images.githubusercontent.com/32936898/199681363-1094a0be-85ca-49cf-a410-19b3d7965120.png","https://user-images.githubusercontent.com/32936898/199681368-c34c2be7-e0d8-43ea-8c2c-d3e865da6aeb.png"],"categories":[],"sub_categories":[],"readme":"# sphinxcontrib-eval\n\n[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/sphinx-contrib/eval/main.svg)](https://results.pre-commit.ci/latest/github/sphinx-contrib/eval/main)\n[![github/workflow](https://github.com/sphinx-contrib/eval/actions/workflows/main.yml/badge.svg)](https://github.com/sphinx-contrib/eval/actions)\n[![codecov](https://codecov.io/gh/sphinx-contrib/eval/branch/main/graph/badge.svg)](https://codecov.io/gh/sphinx-contrib/eval)\n[![readthedocs](https://shields.io/readthedocs/sphinxcontrib-eval)](https://sphinxcontrib-eval.readthedocs.io)\n\n[![github/downloads](https://shields.io/github/downloads/sphinx-contrib/eval/total)](https://github.com/sphinx-contrib/eval/releases)\n[![github/downloads/latest](https://shields.io/github/downloads/sphinx-contrib/eval/latest/total)](https://github.com/sphinx-contrib/eval/releases/latest)\n[![github/issues](https://shields.io/github/issues/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/issues)\n[![github/issues-closed](https://shields.io/github/issues-closed/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/issues?q=is%3Aissue+is%3Aclosed)\n[![github/issues-pr](https://shields.io/github/issues-pr/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/pulls)\n[![github/issues-pr-closed](https://shields.io/github/issues-pr-closed/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/pulls?q=is%3Apr+is%3Aclosed)\n[![github/discussions](https://shields.io/github/discussions/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/discussions)\n[![github/milestones](https://shields.io/github/milestones/all/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/milestones)\n[![github/forks](https://shields.io/github/forks/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/network/members)\n[![github/stars](https://shields.io/github/stars/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/stargazers)\n[![github/watchers](https://shields.io/github/watchers/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/watchers)\n[![github/contributors](https://shields.io/github/contributors/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/graphs/contributors)\n[![github/commit-activity](https://shields.io/github/commit-activity/w/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/graphs/commit-activity)\n[![github/last-commit](https://shields.io/github/last-commit/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/commits)\n[![github/release-date](https://shields.io/github/release-date/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/releases/latest)\n\n[![github/license](https://shields.io/github/license/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval/blob/main/LICENSE)\n[![github/languages](https://shields.io/github/languages/count/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n[![github/languages/top](https://shields.io/github/languages/top/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n[![github/directory-file-count](https://shields.io/github/directory-file-count/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n[![github/code-size](https://shields.io/github/languages/code-size/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n[![github/repo-size](https://shields.io/github/repo-size/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n[![github/v](https://shields.io/github/v/release/sphinx-contrib/eval)](https://github.com/sphinx-contrib/eval)\n\n[![pypi/status](https://shields.io/pypi/status/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#description)\n[![pypi/v](https://shields.io/pypi/v/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#history)\n[![pypi/downloads](https://shields.io/pypi/dd/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#files)\n[![pypi/format](https://shields.io/pypi/format/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#files)\n[![pypi/implementation](https://shields.io/pypi/implementation/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#files)\n[![pypi/pyversions](https://shields.io/pypi/pyversions/sphinxcontrib-eval)](https://pypi.org/project/sphinxcontrib-eval/#files)\n\nEvaluate shell command or python code in sphinx and myst.\n\n## Install\n\nSee [here](https://sphinxcontrib-eval.readthedocs.io/en/latest/resources/install.html).\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 \u0026\u0026 sphinx-build . _build/html \u0026\u0026 cd -`, CWD will be `docs`, which is\nthe default setting of \u003chttps://readthedocs.org\u003e. So if your code structure is\nlike\n\n```console\n$ tree --level 1\n .\n├──  docs\n├──  scripts\n├──  src\n└──  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\n**Note**: A more \"sphinx\" solution is\n[sphinxcontrib-autofile](https://github.com/sphinx-contrib/autofile).\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/sphinx-contrib/eval/blob/main/scripts/generate-api.md.pl)\nreplaces all `src/translate_shell/XXX.py`s 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- \u003chttps://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L4\u003e\n  more stardicts.\n- \u003chttps://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/translators/stardict/__init__.py#L5\u003e\n  Create different subclasses for different dict to get phonetic, explains\n- \u003chttps://github.com/Freed-Wu/tranlate-shell/tree/main/src/translate_shell/ui/repl.py#L33\u003e\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 ..\nshopt -s globstar\nscripts/generate-todo.md.pl src/**/*.py\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\n**Note**: A more \"sphinx\" solution is\n[sphinxcontrib-requirements-txt](https://github.com/sphinx-contrib/requirements-txt).\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/sphinx-contrib/eval/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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-contrib%2Feval","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsphinx-contrib%2Feval","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsphinx-contrib%2Feval/lists"}