README文件的最后一部分是关于如果您想通过代码贡献来参与其中。

开发安装

要在开发模式下安装，请使用以下命令

git clone git+https://github.com/cthoyt/docdata.git
cd docdata
pip install -e .

更新包模板

本项目使用cruft来保持模板（即配置、贡献指南、文档配置）与上游cookiecutter包同步。使用以下命令更新

pip install cruft
cruft update

关于Cruft更新命令的更多信息请参阅此处。

🥼 测试

在克隆存储库并使用pip install tox tox-uv安装tox后，可以使用以下命令有选择地运行tests/文件夹中的单元测试

tox -e py

此外，这些测试会自动在每次提交时通过GitHub Action重新运行。

📖 构建文档

可以使用以下命令在本地构建文档

git clone git+https://github.com/cthoyt/docdata.git
cd docdata
tox -e docs
open docs/build/html/index.html

文档会自动安装包以及pyproject.toml中指定的docs额外部分。可以添加texext等sphinx插件。此外，还需要将它们添加到docs/source/conf.py中的extensions列表中。

可以使用ReadTheDocs使用以下指南部署文档。该.readthedocs.yml YAML文件包含您需要的所有配置。您还可以在GitHub上设置持续集成，以检查Sphinx是否可以在隔离环境中构建文档（即使用tox -e docs-test），并且ReadTheDocs也可以构建它。

配置ReadTheDocs

1. 使用您的GitHub账户登录ReadTheDocs，在https://readthedocs.org/accounts/login/?next=/dashboard/安装集成
2. 通过转到https://readthedocs.org/dashboard/import然后点击您的存储库旁边的加号图标导入您的项目
3. 在下一屏上，您可以使用更风格化的名称（例如，带有空格和大写字母）重命名存储库
4. 点击“下一步”，您就可以开始了！

📦 发布版本

配置Zenodo

Zenodo是一个长期存档系统，为每个包的每个版本分配DOI。

1. 使用此链接通过GitHub登录Zenodo：https://zenodo.org/oauth/login/github/?next=%2F。这将带您到一个列出所有组织并要求您批准在GitHub上安装Zenodo应用程序的页面。点击任何您想要启用集成的组织旁边的“授予”按钮，然后点击大绿色的“批准”按钮。此步骤只需执行一次。
2. 导航到https://zenodo.org/account/settings/github/，其中列出了您的所有GitHub存储库（包括您的用户名和您启用的任何组织）。点击任何相关存储库的开/关切换按钮。在创建新的存储库时，您需要回到这里

完成这些步骤后，您就可以开始了！在GitHub上进行“发布”操作后（下面提供了这些步骤），您可以导航到https://zenodo.org/account/settings/github/repository/cthoyt/docdata以查看发布版本的DOI并链接到Zenodo记录。

在Python包索引（PyPI）中注册

您只需要执行以下步骤一次。

1. 在 Python 包索引（PyPI） 上注册账户
2. 导航到 https://pypi.ac.cn/manage/account 并确保您已验证了您的电子邮件地址。默认情况下，可能不会发送验证邮件，因此您可能需要单击地址旁边的“选项”下拉菜单，然后才能到达“重新发送验证邮件”按钮
3. 自2023年底以来，PyPI要求进行两步验证（请参阅此PyPI博客文章）。这意味着您必须首先生成账户恢复代码，然后设置两步验证
4. 从 https://pypi.ac.cn/manage/account/token 生成API令牌

配置您的机器连接到PyPI

您必须为每台机器执行以下步骤。在您的家目录中创建一个名为 .pypirc 的文件，并包括以下内容

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = <the API token you just got>

# This block is optional in case you want to be able to make test releases to the Test PyPI server
[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = <an API token from test PyPI>

请注意，由于PyPI要求基于令牌的验证，我们使用 __token__ 作为用户名，无需更改。如果您已经有包含 [distutils] 节的 .pypirc 文件，请确保存在 index-servers 键，并且 pypi 在其关联列表中。有关配置 .pypirc 文件的更多信息，请参阅此处。

上传到PyPI

在开发模式下安装包并使用 pip install tox tox-uv 安装 tox 后，从shell中运行以下命令

tox -e finish

此脚本执行以下操作

1. 使用 Bump2Version 将 pyproject.toml、CITATION.cff、src/docdata/version.py 和 docs/source/conf.py 中的版本号切换为不带 -dev 后缀
2. 使用 build 将代码打包成tar存档和wheel格式
3. 使用 twine 上传到PyPI。
4. 推送到GitHub。您需要创建一个与版本提升的提交对应的发行版
5. 将版本提升到下一个补丁。如果您进行了重大更改并希望通过次要版本提升版本，您可以在之后使用 tox -e bumpversion -- minor

在GitHub上发布

1. 导航到 https://github.com/cthoyt/docdata/releases/new 以草拟一个新的发行版
2. 单击“选择标签”下拉菜单并选择您刚刚制作的发行版对应的标签
3. 单击“生成发行说明”按钮以获取最近更改的快速概述。根据需要修改标题和描述
4. 单击大绿色的“发布发行版”按钮

这将触发Zenodo为您的发行版分配DOI。