生成RestructuredText的简单Python API。
项目描述
RstCloth
reStructuredText是一种功能强大、以人为中心、定义良好、灵活的标记语言，具有强大的工具，可以轻松愉快地编写和维护文本。人类可以无需复杂编辑工具的辅助编辑reStructuredText，生成的源代码易于操作和处理。
作为替代和补充，RstCloth是用于程序化编写良好格式reStructuredText的Python API。
项目文档可在此处找到
开发者说明
仓库基于thclark/python-library-template
- vscode
.devcontainer - black风格
- sphinx文档和一些示例以及自动构建
- pre-commit钩子
- tox测试
- github actions ci + cd
- 代码覆盖率
使用VSCode
查看仓库并使用远程的 .devcontainer 启动开发，所有东西都预先安装好了。
在其他 IDE 中
使用 poetry --extras docs 安装项目并开始。您还需要安装 pre-commit 以使钩子工作。请
pip install pre-commit
pre-commit install && pre-commit install -t commit-msg
完成这些后，每次提交时都会进行一系列检查，并应用项目文件格式。
如果失败，提交将停止。 重新运行提交将自动修复大多数问题 除了
- flake8 检查... 希望随着时间的推移 Black（它已经自动修复了大多数问题）将消除对其的需求。
- 您必须在成功提交之前自己修复文档（对此没有自动修复！！）。
您也可以在不提交的情况下运行 pre-commit 钩子，例如
pre-commit run black --all-files
或
# -v gives verbose output, useful for figuring out why docs won't build
pre-commit run build-docs -v
贡献
-
请在板上提出问题（或添加您对现有问题的 $0.02）以便维护者知道发生了什么，并可以提供建议/指导。
-
创建 rstcloth 的分支，在新分支上进行更改（有关分支命名规范，请参阅
.pre-commit-config.yaml）。 -
为了让我们更轻松，请使用我们的常规提交模式（如果您正确安装了 pre-commit，它将在您的第一次提交时引导您）来提交您的提交（如果没有，我们将尝试保留您的历史记录，但可能需要 squashmerge，这将丢失您的贡献历史）
-
采用测试驱动开发方法来实现新功能或修复错误。
-
向
rstcloth维护者询问 在哪里 提交您的拉取请求。我们将根据路线图创建一个版本分支，您可以在此分支上提交您的 PR。我们将帮助审查更改并改进 PR。 -
一旦检查通过，新代码的测试覆盖率 >=95%，文档已更新且审查通过，我们将将其合并到版本分支中。
发布流程
使用 conventional-commits 和 GitHub Actions 自动化发布。
文档
自动构建文档
在 VSCode .devcontainer 中，RestructuredText 扩展应为您实时构建文档（右键单击 .rst 文件并单击“打开预览”）。
每次提交时，文档将在预配置环境中自动构建。根据 pre-commit 的工作方式，除非文档构建，否则不允许您提交，这样我们就可以避免在任何提交 sha 上将损坏的文档推送到主仓库，这样我们就可以依赖构建工作。
手动构建文档
如果您需要构建文档
安装 doxgen。在 mac 上，这是 brew install doxygen；其他系统可能有所不同。
安装 sphinx 和构建文档所需的其他要求
poetry install --extras docs
运行构建过程
sphinx-build -b html docs/source docs/build
下载文件
下载您平台的文件。如果您不确定该选择哪个，请了解更多关于安装包的信息。