如何撰写并贡献文档

openEuler Embedded采用了Sphinx来构建文档，生成html静态面，并最终托管在gitee pages上。 本章主要简述如何通过Sphinx向openEuler Embedded贡献文档。

关于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 。

如何贡献文档（Linux环境）

• git clone yocto-meta-openeuler仓库

  git clone https://gitee.com/openeuler/yocto-meta-openeuler.git
  # 注意切换到你要贡献的资料分支，资料也在此仓库中亦按分支区分
  

• 环境准备

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

  pip3 install sphinx
  pip3 install --user -r yocto-meta-openeuler/scripts/requirements-doc.txt
  

• 编辑文档

  相关文档源码位于 docs/source 目录，根据你的需要修改或新增相应的文档，新增文档命名要按照Linux命名方法命名为xxx_yyy_zzz.rst，请按照如下目录规则布局文档:

  文档目录布局

  文件/目录名	用途
  index.rst	目录页
  introduction	openEuler Embedded总揽与简介
  getting_started	openEuler Embedded快速使用入门
  features	openEuler Embedded主要特性介绍
  yocto	openeuler Embedded的Yocto构建系统
  release	openEuler Embedded的发布说明

• 编译文档

  在 docs 目录下编译文档

  make html
  

  编译成功之后，可打开 docs/build/html/*.html 查看最终生成的网页形式的文档。

• 提交修改

  像提交代码一样，把所有的修改以commit的形式提交，然后在gitee上生成PR提交到openEuler Embedded对应的仓库, 经过审查后， 修改就会被CI自动编译并发布。

  Attention

  • 新增文档必须将该文档加入到对应目录的index索引文件中，新增目录必须将目录和索引加入到 docs/source/getting_started/index.html 中，图片加入到 docs/image/ 目录中。

  • git提交时标题加上 doc: 开头，例如doc:(空一格)modify doc。并加上Signed-off-by，与提交的message中间空一行。

  • 提交PR时标题要以 [文档] 开头，例如[文档]：修改xx文档内容。如果有issue，要和issue进行关联。

如何贡献文档（Windows环境）

• git clone yocto-meta-openeuler仓库

  git clone https://gitee.com/openeuler/yocto-meta-openeuler.git
  # 注意切换到你要贡献的资料分支，资料也在此仓库中亦按分支区分
  

• 环境准备

sphinx依赖于python，所以要先安装python环境，并安装pip工具和sphinx。

1.下载并安装python3 for windows：https://www.python.org/downloads/windows/

• 下载python3.10.3安装包

• 安装python3，默认安装或自定义安装路径如 D:/python3

• 添加到系统路径，如python3安装到 D:/python3 下，则将 D:/Python3 和 D:/Python3/Scripts 添加到系统环境变量Path中，后面那个路径一般是easy_install，pip等扩展工具安装的目录。

• 安装pip3，默认pip3已经在 Scripts 目录中了无需额外安装，如果没有，则下载并安装：

  • 下载 get-pip.py 脚本到 Scripts 目录，地址： https://bootstrap.pypa.io/get-pip.py

  • 在 Scripts 目录运行下面命令安装pip3：

    python3 get-pip.py
    

2.使用pip3安装sphinx（运行此命令）:

pip3 install sphinx

3.在python的 Scripts 目录下，找到easy_install，在控制台下执行该命令，在命令行输入

easy_install sphinx

easy_install可以自动下载并安装sphinx以及它所依赖的其他模块。

4.安装完成后，命令行会提示Finished Processing dependencies for shinx

5.在命令行输入sphinx-build，如果在安装python时，没有设置环境变量，可能会弹出sphinx-build不是内部或者外部命令。

6.通过pip3按照如下命令安装相应的python软件包，包括sphinx、文档主题等：

pip3 install --user -r yocto-meta-openeuler/scripts/requirements-doc.txt

• 创建工程

安装完sphinx后，会在python的 Scripts 目录下产生sphinx-quickstart，确保该目录已经添加到系统环境变量中。

1.启动cmd。进入要创建sphinx文档的目录，如 D:/Learn/python 。

cd /d d:\Learn\python

或直接在 D:/Learn/python 目录下，按住Shift，点击鼠标右键选择在此处打开Powershell窗口(S)。

2.执行下面过程，创建编写Python文档的工程，其实设置工程名、作者名、版本号，其他默认就行。我们这里把source和build两个目录分开，因为这样比较方便。

PS D:\Learn\python> sphinx-quickstart
Welcome to the Sphinx 3.5.4 quickstart utility.

Please enter values for the following settings (just press Enter to accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate "source" and "build" directories within the root path.

> Separate source and build directories (y/n) [n]: y

The project name will occur in several places in the built documentation.

> Project name: embedded
> Author name(s): yang
> Project release []: 1.0.0

If the documents are to be written in a language other than English, you can select a language here by its language code. Sphinx will then translate text that it generates into that language.

For a list of supported codes, see https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.

> Project language [en]:

Creating file D:\Learn\python\source\conf.py.
Creating file D:\Learn\python\source\index.rst.
Creating file D:\Learn\python\Makefile.
Creating file D:\Learn\python\make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file D:\Learn\python\source\index.rst and create other documentation source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

PS D:\Learn\python>

安装完成后，将clone的 yocto-meta-openeuler/docs/ 目录下的 image 和 source 目录全部复制到新建工程目录（ D:/Learn/python ）内并替换原文件。

• 编辑文档

相关文档源码位于 docs/source 目录，根据你的需要修改或新增相应的文档，新增文档命名要按照Linux命名方法命名为xxx_yyy_zzz.rst，请按照如下目录规则布局文档:

文档目录布局

文件/目录名	用途
index.rst	目录页
introduction	openEuler Embedded总揽与简介
getting_started	openEuler Embedded快速使用入门
features	openEuler Embedded主要特性介绍
yocto	openeuler Embedded的Yocto构建系统
release	openEuler Embedded的发布说明

• 编译文档

将 docs 下的 image 和 source 目录内新增和修改的文件全部复制替换到工程（D:/Learn/python）对应目录内，在该目录下编译文档

.\make html

编译成功之后，可以打开 build/html 目录下的html文件查看最终生成的网页形式的文档。

• 提交修改

像提交代码一样，把所有的修改以commit的形式提交，然后在gitee上生成PR提交到openEuler Embedded对应的仓库, 经过审查后，修改就会被CI自动编译并发布。

Attention

• 新增文档必须将该文档加入到对应目录的index索引文件中，新增目录必须将目录和索引加入到 docs/source/getting_started/index.html 中，图片加入到 docs/image/ 目录中。

• git提交时标题加上 doc: 开头，例如doc:(空一格)modify doc。并加上Signed-off-by，与提交的message中间空一行。

• 提交PR时标题要以 [文档] 开头，例如[文档]：修改xx文档内容。如果有issue，要和issue进行关联。

1

Sphinx官方网站

2

reStructuredText维基百科

3

reStructuredText简易教程