贡献指南

我们欢迎并感谢对 PREP-SHOT 库的贡献。贡献流程如下:

开发流程

  1. 创建 Issue

    如果你发现 bug 或有改进 / 新功能的想法,请创建 issue。

  2. Fork 仓库

    你可以在 GitHub 上 fork PREP-SHOT 仓库。

  3. 创建分支

    在你 fork 的仓库中创建新分支,并以正在处理的功能或修复命名。

  4. 提交修改

    在该分支中进行修改。完成改进或 bug 修复后,使用有意义的提交信息提交。

  5. Run Tests To execute all tests, navigate to the root directory of PREP-SHOT and run:

python -m unittest discover -s tests

检查代码是否符合 PEP8,运行:

pylint run.py
pylint prepshot

  1. 发起 Pull Request

    从你 fork 的仓库向主 PREP-SHOT 仓库发起 pull request。在 PR 描述中说明你的修改。

  2. 代码评审

    PREP-SHOT 维护者会评审你的代码。他们可能会在代码合入主分支前要求改动或改进。

贡献代码时请按需更新测试,并遵循项目其他部分既有的编码规范。

构建文档

文档使用 Sphinx 构建。构建前请先用以下命令安装所需包:

pip install -r docs/requirements.txt

随后可用以下命令构建文档:

cd doc
make clean
make html

文档将构建在 doc/build 目录下。

贡献规范

PREP-SHOT 采用 Python 编写,遵循 PEP8 编码规范。请确保你的代码符合 PEP8。可使用 Pylint 工具检查 PEP8 合规性。

Translating the Documentation

Translations live in-tree at doc/source/locale/<lang>/LC_MESSAGES/*.po (one .po file per RST source file). The shipped Chinese (zh_CN) translation is incomplete; only the 术语表 is currently translated. Help with the rest is welcome.

To translate (or update) a single page:

# 1. Extract / refresh the .pot template files from the English RST
sphinx-build -b gettext doc/source doc/build/gettext

# 2. Update the .po files for your target language
sphinx-intl update -p doc/build/gettext -l zh_CN -d doc/source/locale

# 3. Edit doc/source/locale/zh_CN/LC_MESSAGES/<page>.po
#    Fill in the empty msgstr "" entries with translations.

# 4. Compile .po -> .mo and build the Chinese site locally
sphinx-intl build -d doc/source/locale
READTHEDOCS_LANGUAGE=zh_CN sphinx-build -b html doc/source doc/build/html-zh

# 5. Check the result in doc/build/html-zh/, then commit only the
#    .po files (the .mo is regenerated on every build).

Adding a new language. Pick the locale code (e.g. ja, de, es) and uncomment the entry in supported_languages in doc/source/conf.py. Then run step 2 above with your locale code instead of zh_CN. Once at least one page is meaningfully translated, request that a maintainer create the corresponding "translation" project on Read the Docs so the language switcher picks it up.

Reviewing a translation. Native speakers are very welcome to review translated .po files for tone and accuracy. Open a PR with your suggested changes; tag a maintainer for merging.