如何贡献文档

SIG Zephyr与Zephyr Project一样采用了Sphinx来来构建文档，生成html静态面，并最终托管在gitee pages上。 本章主要简述如何通过Sphinx撰写文档并贡献给SIG Zephyr。

关于Sphinx

这里直接引用sphinx官方网站 [1] 上的介绍：

Sphinx是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档
它最初是为Python文档创建的，它具有出色的工具，可用于各种语言的软件项目文档

输出格式: HTML（包括Windows HTML帮助），LaTeX（适用于可打印的PDF版本），ePub，
Texinfo，手册页，纯文本

广泛的交叉引用: 语义标记和功能，类，引用，词汇表术语和类似信息的自动链接
分层结构: 轻松定义文档树，自动链接到平级，上级和下级
自动索引: 一般索引以及特定于语言的模块索引
代码处理: 使用Pygments荧光笔自动突出显示
扩展: 自动测试代码片段，包含Python模块（API文档）中的文档字符串等
贡献的扩展: 用户在第二个存储库中贡献了50多个扩展;其中大多数可以从PyPI安装

更多的使用细节可以前往其 官方网站 查找

关于reStructuredText语法

依据维基百科 [2] 的介绍:

reStructuredText（RST、ReST或reST）是一种用于文本数据的文件格式，主要用于 Python 编程语言社区的技术文档。
它是Python Doc-SIG（Documentation Special Interest Group）的Docutils项目的一部分，旨在为Python创建
一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation（pod）的工具。Docutils可以从Python程序
中提取注释和信息，并将它们格式化为各种形式的程序文档

reStructuredText的语法与Markdown十分类似，但能以更好的结构化的方式撰写专业文档，vscode中也有相应的插件提供辅助。 reStructuredText的语法无需专门记忆，需要用到时再去查询即可，具体可以参考 [3] 。

如何贡献文档

  • git clone文档源码仓库

    git clone https://gitee.com/openeuler/zephyr-cn.git

  • 环境准备

    如果你已经准备好了Zephyr的开发环境，那么可以直接跳过该步。

    如果你只是开发文档的话，那么你需要准备好python3, 然后通过pip3安装相应的软件包，包括sphinx、文档主题等：

    pip3 install --user -r zephyr-CN/doc/requirements-doc.txt

  • 编辑文档

    相关文档源码位于 doc/source 目录，根据你的需要修改或新增相应的文档，请按照如下目录规则布局文档:

    文档目录布局

    文件/目录名

    用途

    index.rst

    目录页

    application

    基于Zephyr的应用

    develop

    深入zephyr，如内核，设备驱动

    introduction

    介绍与总揽

    images

    图片所在目录

  • 编译文档

    在 doc 目录下编译文档

    make html #windows下可能需要nmake

    编译成功之后，可以打开 doc/_build/html/index.html 查看最终效果

  • 提交修改

    像提交代码一样，把所有的修改以commit的形式提交，并在gitee上生成PR, 经过SIG-Zephyr审查后，修改就会被发布。