docs-that-run
docs-that-run 是一個輕量級的 Markdown 文件驗證工具。它只會辨識明確標記
dtr-run 的 Python 與 Bash fenced code block，並在使用者明確允許及確認後，
按照文件中的順序執行。
功能範圍
- 只讀取本機
.mdMarkdown 文件。 - 只支援 Python（
python、py）與 Bash（bash、sh）。 - 只處理語言標籤後含有
dtr-run的程式碼區塊；此 marker 區分大小寫，必須使用完全相同的小寫拼法。 - 預設只掃描，不執行任何程式碼。
- 必須提供
--allow-exec，並在提示中回答y才會執行。 - 每個程式碼區塊預設最多執行 30 秒。
- 區塊依照 Markdown 中的順序執行。
- 同一次執行共用一個保留的暫存工作目錄，因此可以跨區塊共享檔案。
- 每個區塊使用獨立程序，不保留 Python 狀態、
cd或export狀態。 - 顯示成功或失敗、stdout、stderr、執行時間與工作目錄。
需求
- Python 3.9 或更新版本
- 若要執行 Bash 區塊，本機必須有 Bash。Windows 可使用 Git for Windows 提供的 Bash。
本工具不會下載遠端文件，也不會替程式碼安裝依賴套件。
安裝
從專案根目錄安裝：
python -m pip install .
開發與測試安裝：
python -m pip install -e ".[test]"
使用
未指定檔案時掃描 README.md：
dtr
掃描指定檔案：
dtr README.md
掃描多個檔案：
dtr README.md examples/sample_readme.md
以上指令都不會執行程式碼。只有明確加入 --allow-exec 才會進入執行確認：
dtr README.md --allow-exec
看到確認提示後輸入 y 才會執行；輸入其他內容或無法讀取輸入時會取消。
標記語法
以下是可放入其他 Markdown 文件的標記語法展示：
```python dtr-run
print("Hello from docs-that-run")
```
```bash dtr-run
printf '%s\n' 'shared from Bash' > shared_file.txt
```
```python dtr-run
from pathlib import Path
print(Path("shared_file.txt").read_text(encoding="utf-8").strip())
```
沒有 dtr-run 的區塊只會作為一般文件範例，不會執行：
print("This block is not executable")
測試
pytest
測試用 Markdown 位於 tests/fixtures/，可手動執行的完整範例位於
examples/sample_readme.md。
安全注意事項
--allow-exec 會在本機直接執行文件中的程式碼。v0.1 沒有沙箱、CPU、
記憶體或檔案系統隔離；請只執行你信任的文件。
v0.1 限制
- 不支援 Python 與 Bash 以外的語言。
- 不支援遠端文件或遠端 repository。
- 不安裝程式碼所需依賴，也不管理虛擬環境。
- 不支援互動式、平行或圖形介面程式。
- 不在區塊之間共享 Python 變數、shell 環境變數或
cd狀態。 - 只輸出終端機報告，不產生 HTML、JSON 或 JUnit 報告。
- 沒有沙箱與資源限制；timeout 只限制執行時間。
License
MIT
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file docs_that_run-0.1.2.tar.gz.
File metadata
- Download URL: docs_that_run-0.1.2.tar.gz
- Upload date:
- Size: 16.6 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8cf3b41c5983c89e276be483dd674c9dcad4c15a56050db217e9ce6402b5cfc2
|
|
| MD5 |
66f96ff837cf949f579dd247fd16bcce
|
|
| BLAKE2b-256 |
7b40df4fd025b503bc1afff839667e1df4a9ca421d7bea73550ff41669dc364a
|
Provenance
The following attestation bundles were made for docs_that_run-0.1.2.tar.gz:
Publisher:
release.yml on gfr211306-crypto/docs-that-run
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
docs_that_run-0.1.2.tar.gz -
Subject digest:
8cf3b41c5983c89e276be483dd674c9dcad4c15a56050db217e9ce6402b5cfc2 - Sigstore transparency entry: 2735654225
- Sigstore integration time:
-
Permalink:
gfr211306-crypto/docs-that-run@cd423d9fbfcb3e7a91bbeae814c0a9c6815b781d -
Branch / Tag:
refs/tags/v0.1.2 - Owner: https://github.com/gfr211306-crypto
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@cd423d9fbfcb3e7a91bbeae814c0a9c6815b781d -
Trigger Event:
release
-
Statement type:
File details
Details for the file docs_that_run-0.1.2-py3-none-any.whl.
File metadata
- Download URL: docs_that_run-0.1.2-py3-none-any.whl
- Upload date:
- Size: 13.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
629acb27a18712f397cf44edc0fdca65a51a15c6befb0b5d1dfd3329abd6d7c5
|
|
| MD5 |
8e56501d9dae573231307e1e8032d6cc
|
|
| BLAKE2b-256 |
8f0d115d9020e20fdf2aa0387682493e0cfc2ad2f25e60a453f7b957641a92d8
|
Provenance
The following attestation bundles were made for docs_that_run-0.1.2-py3-none-any.whl:
Publisher:
release.yml on gfr211306-crypto/docs-that-run
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
docs_that_run-0.1.2-py3-none-any.whl -
Subject digest:
629acb27a18712f397cf44edc0fdca65a51a15c6befb0b5d1dfd3329abd6d7c5 - Sigstore transparency entry: 2735654536
- Sigstore integration time:
-
Permalink:
gfr211306-crypto/docs-that-run@cd423d9fbfcb3e7a91bbeae814c0a9c6815b781d -
Branch / Tag:
refs/tags/v0.1.2 - Owner: https://github.com/gfr211306-crypto
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@cd423d9fbfcb3e7a91bbeae814c0a9c6815b781d -
Trigger Event:
release
-
Statement type:
