ustclug / ustclug/mirrorhelp

建议增加贡献者指南

Open
#40 4 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
642
Forks
163
Avg merge
18h 30m
Merged PRs (30d)
1

Description

刚刚提了个 PR,增加了 EPEL 和 MariaDB 的帮助文档。由于没接触过 SphinxreStructureText ,很是费了一番功夫。

希望提供一份贡献者指南,以帮助初学者快速入门,并保证文档风格的统一。

建议包含以下内容:

  • 如何在本地预览文档(环境要求,安装依赖)
  • 如何添加一个新文档(文件位置、名称,添加后要相应修改哪些地方)
  • 帮助文档的结构(需包含那些部分)
  • 统一风格,比如
    • 各级标题分别使用哪种标识符(= - ` : ' " ~ ^ _ * + # < >),长度多少(目前很多 "WARNING: Title underline too short")
    • Code block 的标识符(::)是单独写在一行,还是写在前一句的末尾?偏爱前者,以免在中文中混入英文冒号
    • 支持多个发行版、同一发行版的多个版本的源,“使用说明”一节是列出所有组合下的配置文件内容,还是提供命令修改默认的配置文件(比如我提的 PR 中对 EPEL 的处理),亦或说明一下原理,让用户自己手动处理?
    • “相关链接”一节使用 Field List,还是无序列表并且使用 Embedded URL 形式不直接显示链接地址。偏爱后者,以免标题、链接过长时分行显示,不美观

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.