如何撰写并贡献文档

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:/Python3D:/Python3/Scripts 添加到系统环境变量Path中,后面那个路径一般是easy_install,pip等扩展工具安装的目录。

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

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/ 目录下的 imagesource 目录全部复制到新建工程目录( 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 下的 imagesource 目录内新增和修改的文件全部复制替换到工程(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简易教程