zhou
32ca8c1208
CI / Lint, Typecheck & Test (push) Successful in 1m57s
1. 新建 docs/ Sphinx 文档结构 (conf.py + 8 个 rst 章节), napoleon 支持 Google/NumPy docstring, rtd 主题, 自动生成 API 参考与错误家族文档 2. 新建 .readthedocs.yaml 配置, pyproject.toml 加 docs 依赖 3. 删除 runner.py 的 _apply_verbose_to_graph 死代码及对应测试 (功能已移入 executors.run 统一处理) 4. 更新 README: CLI 示例改为 pf 统一入口, 模块结构表补全 cli/pf.py/cli/configs/cli/_ops 等模块 5. 修复版本不一致 (pyproject.toml 0.3.5 → 0.4.5) 6. 加文档徽章链接到 ReadTheDocs
159 lines
3.4 KiB
ReStructuredText
159 lines
3.4 KiB
ReStructuredText
pf 统一 CLI 入口
|
||
================
|
||
|
||
所有工具通过 ``pf <tool> [command] [options]`` 调用。工具定义在 ``cli/configs/`` 目录下的 YAML 文件中。
|
||
|
||
基本用法
|
||
--------
|
||
|
||
.. code-block:: bash
|
||
|
||
pf # 列出所有可用工具
|
||
pf filedate # 查看 filedate 工具帮助
|
||
pf filedate add a.txt # 调用 filedate 的 add 子命令
|
||
pf gitt c # 调用 gittool 的 c 子命令
|
||
pf pymake b # 调用 pymake 的 b 别名
|
||
|
||
全局选项
|
||
--------
|
||
|
||
所有 YAML 工具支持以下全局选项：
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
:widths: 25 75
|
||
|
||
* - 选项
|
||
- 说明
|
||
* - ``--dry-run``
|
||
- 仅打印执行计划，不执行
|
||
* - ``--quiet`` / ``-q``
|
||
- 减少输出，不显示执行过程
|
||
* - ``--strategy``
|
||
- 执行策略（``sequential`` / ``thread`` / ``async`` / ``dependency``）
|
||
* - ``--list``
|
||
- 列出所有任务名后退出
|
||
|
||
默认 ``verbose`` 开启，显示执行过程（任务开始/命令/返回码/任务成功）。``--quiet`` 关闭。
|
||
|
||
YAML 配置工具
|
||
--------------
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
:widths: 20 15 65
|
||
|
||
* - 工具
|
||
- 别名
|
||
- 说明
|
||
* - ``filedate``
|
||
- ``fd``
|
||
- 文件日期处理
|
||
* - ``filelevel``
|
||
- ``fl``
|
||
- 文件等级重命名
|
||
* - ``folderback``
|
||
- ``fb``
|
||
- 文件夹备份
|
||
* - ``folderzip``
|
||
- ``fz``
|
||
- 文件夹压缩
|
||
* - ``gittool``
|
||
- ``gitt``
|
||
- Git 执行工具
|
||
* - ``lscalc``
|
||
- ``ls``
|
||
- LS-DYNA 计算工具
|
||
* - ``packtool``
|
||
- ``pack``
|
||
- Python 打包工具
|
||
* - ``pdftool``
|
||
- ``pdf``
|
||
- PDF 文件工具集
|
||
* - ``piptool``
|
||
- ``pip``
|
||
- pip 包管理工具
|
||
* - ``screenshot``
|
||
- ``ss``
|
||
- 截图工具
|
||
* - ``sshcopyid``
|
||
- ``ssh``
|
||
- SSH 密钥部署工具
|
||
* - ``autofmt``
|
||
- ``af``
|
||
- 自动格式化工具
|
||
* - ``bumpversion``
|
||
- ``bump``
|
||
- 版本号自动管理工具
|
||
|
||
传统工具
|
||
--------
|
||
|
||
.. list-table::
|
||
:header-rows: 1
|
||
:widths: 20 80
|
||
|
||
* - 工具
|
||
- 说明
|
||
* - ``pymake``
|
||
- 构建工具（替代 Makefile），如 ``pf pymake b`` 构建
|
||
* - ``yamlrun``
|
||
- YAML pipeline 执行器，``pf yamlrun pipeline.yaml``
|
||
* - ``profiler``
|
||
- 性能分析
|
||
* - ``emlman``
|
||
- 邮件管理
|
||
* - ``reseticon``
|
||
- 重置图标缓存
|
||
|
||
自定义工具
|
||
----------
|
||
|
||
在 ``cli/configs/`` 目录新建 ``<tool>.yaml`` 即可被 ``pf`` 自动发现：
|
||
|
||
.. code-block:: yaml
|
||
|
||
# cli/configs/mytool.yaml
|
||
strategy: sequential
|
||
variables:
|
||
MSG: "hello"
|
||
cli:
|
||
description: "我的工具"
|
||
usage: "pf mytool [command]"
|
||
subcommands:
|
||
greet:
|
||
help: "打招呼"
|
||
jobs:
|
||
greet:
|
||
cmd: ["echo", "${MSG}"]
|
||
|
||
执行::
|
||
|
||
pf mytool greet
|
||
|
||
CliRunner（编程式）
|
||
-------------------
|
||
|
||
``CliRunner`` 把多个 Graph 映射为命令行子命令，适合构建项目专属构建工具：
|
||
|
||
.. code-block:: python
|
||
|
||
runner = px.CliRunner(
|
||
strategy="sequential",
|
||
description="My Build Tool",
|
||
graphs={
|
||
"clean": clean_graph,
|
||
"build": build_graph,
|
||
"test": test_graph,
|
||
},
|
||
)
|
||
runner.run_cli() # 解析 sys.argv 并执行
|
||
|
||
命令行::
|
||
|
||
pf pymake clean
|
||
pf pymake build --strategy thread
|
||
pf pymake test --dry-run
|
||
pf pymake --list
|
||
pf pymake --quiet
|