如何撰写并贡献文档

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 --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主要特性介绍

    linux

    openEuler Embedded运行相关的内容说明

    infrastructure

    openEuler Embedded基础设施相关内容

    yocto

    openEuler Embedded的Yocto构建系统

    develop_help

    涉及openEuler Embedded开发过程中的一些帮助指导

    bsp

    openEuler Embedded南向支持方面的内容

    release

    openEuler Embedded的发布说明

  • 编译文档

    在 docs 目录下编译文档：

    make html

    编译成功后，可以切换到gitee_pages分支，打开 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安装包

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

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

  • 安装pip3，默认pip3已经在 Scripts 目录中（安装python3时自带），故无需额外安装。如果没有，则下载并安装：

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

pip3 install sphinx

3.在python的 Scripts 目录下，找到easy_install（如没有则需额外安装），在命令行输入

easy_install sphinx

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

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

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主要特性介绍

linux

openEuler Embedded运行相关的内容说明

infrastructure

openEuler Embedded基础设施相关内容

yocto

openEuler Embedded的Yocto构建系统

develop_help

涉及openEuler Embedded开发过程中的一些帮助指导

bsp

openEuler Embedded南向支持方面的内容

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简易教程