建议增加贡献者指南
Open
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 642
- Forks
- 163
- Avg merge
- 18h 30m
- Merged PRs (30d)
- 1
Description
刚刚提了个 PR,增加了 EPEL 和 MariaDB 的帮助文档。由于没接触过 Sphinx 和 reStructureText ,很是费了一番功夫。
希望提供一份贡献者指南,以帮助初学者快速入门,并保证文档风格的统一。
建议包含以下内容:
- 如何在本地预览文档(环境要求,安装依赖)
- 如何添加一个新文档(文件位置、名称,添加后要相应修改哪些地方)
- 帮助文档的结构(需包含那些部分)
- 统一风格,比如
- 各级标题分别使用哪种标识符(= - ` : ' " ~ ^ _ * + # < >),长度多少(目前很多 "WARNING: Title underline too short")
- Code block 的标识符(::)是单独写在一行,还是写在前一句的末尾?偏爱前者,以免在中文中混入英文冒号
- 支持多个发行版、同一发行版的多个版本的源,“使用说明”一节是列出所有组合下的配置文件内容,还是提供命令修改默认的配置文件(比如我提的 PR 中对 EPEL 的处理),亦或说明一下原理,让用户自己手动处理?
- “相关链接”一节使用 Field List,还是无序列表并且使用 Embedded URL 形式不直接显示链接地址。偏爱后者,以免标题、链接过长时分行显示,不美观
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Review the existing help documentation and PR #39, then inspect the Sphinx and reStructuredText setup used for local previews. Document how to add a page, where it belongs, required sections, and the agreed heading, code-block, and link conventions; the checklist in the issue defines the expected coverage.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100