From e13af39a41030136a5b09b49529d8582fa83cfea Mon Sep 17 00:00:00 2001 From: tangwei55170831 <37010490+tangwei55170831@users.noreply.github.com> Date: Mon, 8 May 2023 16:59:05 +0800 Subject: [PATCH] docs: Update development help module links and optimization descriptions 1.update URLs of republish.rst and contribute_doc.rst 2.Optimize descriptions of openeuler_fetch.rst, republish.rst and contribute_doc.rst Signed-off-by: tangwei55170831 --- docs/source/develop_help/contribute_doc.rst | 44 ++++++++++---------- docs/source/develop_help/openeuler_fetch.rst | 26 ++++++------ docs/source/develop_help/republish.rst | 4 +- 3 files changed, 36 insertions(+), 38 deletions(-) diff --git a/docs/source/develop_help/contribute_doc.rst b/docs/source/develop_help/contribute_doc.rst index 6ce70e1b0e0..2722fef56c4 100644 --- a/docs/source/develop_help/contribute_doc.rst +++ b/docs/source/develop_help/contribute_doc.rst @@ -3,7 +3,7 @@ 如何撰写并贡献文档 ################## -openEuler Embedded采用了Sphinx来构建文档，生成html静态面，并最终托管在gitee pages上。 +openEuler Embedded采用Sphinx来构建文档，生成html静态面，并最终托管在gitee pages上。 本章主要简述如何通过Sphinx向openEuler Embedded贡献文档。 关于Sphinx @@ -13,20 +13,18 @@ openEuler Embedded采用了Sphinx来构建文档，生成html静态面，并最 :: - Sphinx是一个工具，可以轻松创建由Georg Brandl编写并根据BSD许可证授权的智能和美观文档 - 它最初是为Python文档创建的，它具有出色的工具，可用于各种语言的软件项目文档 + Sphinx是一个工具，可以轻松地创建出智慧且优雅的文档。它由Georg Brandl创建，并在BSD许可证下授权。 + 它最初是为Python文档创建的。它具有出色的功能，可用于各种语言的软件项目文档 - 输出格式: HTML（包括Windows HTML帮助），LaTeX（适用于可打印的PDF版本），ePub， - Texinfo，手册页，纯文本 + 输出格式: HTML（包括Windows HTML帮助），LaTeX（可打印的PDF版本），ePub，Texinfo，手册页，纯文本 + 丰富的交叉引用: 语义标记以及针对函数，类，引用，词汇表（术语）和相似的信息块的自动链接 + 层次结构: 简单的文本树定义，就能自动地链接到同层（兄弟姐妹）、上一层（父母）以及下一层（子女）的文本位置 + 自动生成目录: 通用索引以及语言模块的目录 + 代码高亮: 使用Pygments荧光笔使代码自动高亮 + 扩展功能: 自动测试代码片段，包括从Python模块（API文档）中的文档字符串 + 贡献的扩展: 用户在第二个存储库中贡献了50多个扩展，其中大多数可以通过PyPI安装 - 广泛的交叉引用: 语义标记和功能，类，引用，词汇表术语和类似信息的自动链接 - 分层结构: 轻松定义文档树，自动链接到平级，上级和下级 - 自动索引: 一般索引以及特定于语言的模块索引 - 代码处理: 使用Pygments荧光笔自动突出显示 - 扩展: 自动测试代码片段，包含Python模块（API文档）中的文档字符串等 - 贡献的扩展: 用户在第二个存储库中贡献了50多个扩展;其中大多数可以从PyPI安装 - -更多的使用细节可以前往其 `官方网站 `_ 查找 +更多的使用细节可以前往 `官方网站 `_ 查找 关于reStructuredText语法 =============================== @@ -38,8 +36,8 @@ openEuler Embedded采用了Sphinx来构建文档，生成html静态面，并最 一组类似于 Java 的 Javadoc 或 Perl 的 Plain Old Documentation（pod）的工具。Docutils可以从Python程序 中提取注释和信息，并将它们格式化为各种形式的程序文档 -reStructuredText的语法与Markdown十分类似，但能以更好的结构化的方式撰写专业文档，vscode中也有相应的插件提供辅助。 -reStructuredText的语法无需专门记忆，需要用到时再去查询即可，具体可以参考 [#rst_tutorial]_ 。 +reStructuredText的语法与Markdown十分类似，但能以更加结构化的方式撰写专业文档，vscode中也有相应的插件提供辅助。 +reStructuredText的语法无需专门记忆，需要用到时再去查询即可，具体可参考 [#rst_tutorial]_ 。 如何贡献文档（Linux环境） ============================== @@ -52,7 +50,7 @@ reStructuredText的语法无需专门记忆，需要用到时再去查询即可 * 环境准备 - 如果你只是开发文档的话，那么你需要准备好python3， 然后通过pip3按照如下命令安装相应的python软件包，包括sphinx、文 + 如果你只进行文档开发的话，那么你需要准备好python3， 然后通过pip3按照如下命令安装对应python软件包，包括sphinx、文 档主题等： .. code-block:: bash @@ -62,7 +60,7 @@ reStructuredText的语法无需专门记忆，需要用到时再去查询即可 * 编辑文档 - 相关文档源码位于 :file:`docs/source` 目录，根据你的需要修改或新增相应的文档，新增文档命名要按照Linux命名方法命名为xxx_yyy_zzz.rst，请按照如下目录规则布局文档: + 相关文档源码位于 :file:`docs/source` 目录，根据你的需要修改或新增相应的文档，新增文档命名需按照Linux命名规则命名为xxx_yyy_zzz.rst，请按照如下目录规则布局文档: .. csv-table:: 文档目录布局 :header: "文件/目录名", "用途" @@ -87,11 +85,11 @@ reStructuredText的语法无需专门记忆，需要用到时再去查询即可 make html - 编译成功之后，可以切换到gitee_pages分支，打开 :file:`docs/build/html/*.html` 查看最终生成的网页形式的文档。 + 编译成功后，可以切换到gitee_pages分支，打开 :file:`docs/build/html/*.html` 查看最终生成的网页形式的文档。 * 提交修改 - 像提交代码一样，把所有的修改以commit的形式提交，然后在gitee上生成PR提交到openEuler Embedded对应的仓库, 经过审查后， + 就像提交代码一样，把所有修改通过commit的形式提交，然后在gitee上创建PR提交到openEuler Embedded对应的仓库, 经过审查后， 修改就会被CI自动编译并发布。 .. attention:: @@ -121,7 +119,7 @@ sphinx依赖于python，所以要先安装python环境，并安装pip工具和sp - 添加到系统路径，如python3安装到 :file:`D:/python3` 下，则将 :file:`D:/Python3` 和 :file:`D:/Python3/Scripts` 添加到系统环境变量Path中，后面那个路径一般是easy_install，pip等扩展工具安装的目录。 -- 安装pip3，默认pip3已经在 :file:`Scripts` 目录中了无需额外安装，如果没有，则下载并安装： +- 安装pip3，默认pip3已经在 :file:`Scripts` 目录中（安装python3时会携带），固无需额外安装；如果没有，则下载并安装： - 下载 :file:`get-pip.py` 脚本到 :file:`Scripts` 目录，地址： https://bootstrap.pypa.io/get-pip.py @@ -242,7 +240,7 @@ easy_install可以自动下载并安装sphinx以及它所依赖的其他模块 * 提交修改 -像提交代码一样，把所有的修改以commit的形式提交，然后在gitee上生成PR提交到openEuler Embedded对应的仓库, 经过审查后，修改就会被CI自动编译并发布。 +像提交代码一样，把所有修改通过commit的形式提交，然后在gitee上创建PR提交到openEuler Embedded对应的仓库, 经过审查后，修改就会被CI自动编译并发布。 .. attention:: @@ -250,6 +248,6 @@ easy_install可以自动下载并安装sphinx以及它所依赖的其他模块 - git提交时标题加上 :file:`doc:` 开头，例如doc:(空一格)modify doc。并加上Signed-off-by，与提交的message中间空一行。 - 提交PR时标题要以 :file:`[文档]` 开头，例如[文档]：修改xx文档内容。如果有issue，要和issue进行关联。 -.. [#sphinx_web] `Sphinx官方网站 `_ +.. [#sphinx_web] `Sphinx官方网站 `_ .. [#rst_wikipedia] `reStructuredText维基百科 `_ -.. [#rst_tutorial] `reStructuredText简易教程 `_ \ No newline at end of file +.. [#rst_tutorial] `reStructuredText简易教程 `_ \ No newline at end of file diff --git a/docs/source/develop_help/openeuler_fetch.rst b/docs/source/develop_help/openeuler_fetch.rst index dfdcde053f0..4f215036c8f 100644 --- a/docs/source/develop_help/openeuler_fetch.rst +++ b/docs/source/develop_help/openeuler_fetch.rst @@ -7,27 +7,27 @@ 特性介绍 *************************** -openeuler_fetch是匹配openEuler Embedded构建镜像时按需从上游源码包自动下载软件包的功能函数，该功能省去了在构建openeuler-image镜像时需要提前下载所有软件包的步骤，因为openEuler Embedded由上百个软件包构成，完全下载耗时耗力，例如，如果你只想编译busybox这一个软件包，你其实是不需要将其他软件包全部下载，你关注的只是构建busybox的依赖软件包下载即可,而openeuler_fetch即可实现按需下载，你只需要初始化完环境即可进入编译环节。 +在openEuler Embedded构建镜像时，需要提前下载所有软件包，而openEuler Embedded由上百个软件包构成，完全下载耗时耗力。功能函数openeuler_fetch解决了该问题，它可以在openEuler Embedded构建镜像时，按需从上游源码包自动下载软件包。例如当你只想编译busybox这一个软件包，而不需要将其他软件包全部下载的时候，使用openeuler_fetch即可实现，你只需要初始化完环境即可进入编译环节。 openeuler_fetch运行机制 *************************** -openeuler_fetch在classes/openeuler.bbclass中实现，函数名为do_openeuler_fetch，该函数在base_do_fetch_prepend中通过bb.build.exec_func()函数调用，即openeuler_fetch运行完还会继续执行do_fetch，这样做的原因是不管openeuler_fetch运行成功与否都可以让fetch继续补充，例如有一款软件包在gitee中不存在，或在配置中配置错误，或者源码目录有相关的改动导致openeuler_fetch运行失败，则do_fetch可以继续完成文件的查找。 +openeuler_fetch在classes/openeuler.bbclass中实现，函数名为do_openeuler_fetch，该函数在base_do_fetch_prepend中通过bb.build.exec_func()函数调用，即openeuler_fetch运行完还会继续执行do_fetch，这样做的原因是不管openeuler_fetch运行成功与否都可以让fetch继续补充，例如有一款软件包在gitee中不存在，或在配置中配置错误，或者源码目录有相关的改动导致openeuler_fetch运行失败，不用担心，do_fetch可以继续完成文件的查找。 openeuler_fetch运行逻辑 *************************** -openeuler_fetch通过以下相关控制变量来完成相关包下载： +openeuler_fetch通过以下控制变量来完成相关包下载： - - OPENEULER_GIT_URL: 远程仓库前缀，默认为https://gitee.com/src-openeuler，该值在.oebuild/local.conf.sample中设置，全局生效，也可以在bb或bbappend文件中设置使之局部生效 + - OPENEULER_GIT_URL: 远程仓库前缀，默认值为https://gitee.com/src-openeuler，该变量在.oebuild/local.conf.sample中设置，全局生效，也可以在bb或bbappend文件中设置使之局部生效 - - OPENEULER_BRANCH: 软件包分支，在下载软件包时会通过该值指定分支名称，该值在.oebuild/local.conf.sample中设置，全局生效，也可以在bb或bbappend文件中设置使之局部生效 + - OPENEULER_BRANCH: 软件包分支，在下载软件包时会通过该变量指定分支名称，该变量在.oebuild/local.conf.sample中设置，全局生效，也可以在bb或bbappend文件中设置使之局部生效 - OPENEULER_REPO_NAME: 软件包名，该名一般和构建包名一致，但在特殊情况下需要改动，例如构建libtool-cross时，构建包名为libtool-cross，因此默认OPENEULER_REPO_NAME为libtool-cross，但是依赖包路径是libtool，则需要将OPENEULER_REPO_NAME改为libtool - OPENEULER_LOCAL_NAME: 软件包本地名称，即软件包在本地路径名称，一般该变量如果不设置则在系统处理时默认和OPENEULER_REPO_NAME一样，该变量意在解决软件包名和本地存储路径不一致问题 - - OPENEULER_SRC_URI_REMOVE: SRC_URI过滤变量，设置该变量可以在bitbake执行fetch之前移除设定的相关uri文件路径，该变量匹配规则时前缀匹配，例如设定OPENEULER_SRC_URI_REMOVE="https git"，则openeuler_fetch在处理时遇到以https和git开头的uri则会去除 + - OPENEULER_SRC_URI_REMOVE: SRC_URI过滤变量，设置该变量可以在bitbake执行fetch之前移除设定的相关uri文件路径，该变量通过前缀进行匹配，例如设定OPENEULER_SRC_URI_REMOVE="https git"，则openeuler_fetch在处理时遇到以https和git开头的uri则会去除 整体openeuler_fetch下载就是依靠以上相关变量完成，由以上变量最终组成git下载参数： @@ -46,11 +46,11 @@ repo_init 运行原理图如下： 如何适配其他软件包 *************************** -在构建openEuler Embedded时经常会引入其他相关包或修改非指定包版本，那么此时该如何做呢？从上文中已经得知openeuler_fetch依赖5个变量来进行下载，内核是例外，因此我们只需要关注其他五个变量即可，接下来我们以busybox为例进行讲解： +在构建openEuler Embedded时经常会引入其他相关包或修改非指定包版本，那么此时该如何做呢？从上文中已经得知openeuler_fetch依赖5个变量来进行下载，内核是例外，因此我们只需要关注这五个变量即可，接下来我们以busybox为例进行讲解： - 如果想要某一个版本的busybox参与构建：在busybox的bbappend文件中设定OPENEULER_BRANCH值为相关版本即可 -- 如果想要使用自有仓库busybox参与构建：在busybox的bbappend文件中设定OPENEULER_GIT_URL为自有空间即可，注意：如果busybox已经下载在本地，则需要手动删除，然后再执行构建 +- 如果想要使用自有仓库的busybox参与构建：在busybox的bbappend文件中设定OPENEULER_GIT_URL为自有空间即可，注意：如果busybox已经下载在本地，则需要手动删除，然后再执行构建 - 如果需要其他代码仓的busybox参与构建，则修改OPENEULER_GIT_URL为其他平台仓域名即可，例如https://github.com/xxx @@ -85,17 +85,17 @@ repo_init 运行原理图如下： 通过repoList设置好需要依赖的包，包结构格式不可更改，PKG_REPO_LIST变量的设定是为在do_openeuler_fetchs中获取依赖的包列表，do_openeuler_fetchs将依次解析PKG_REPO_LIST，并调用do_openeuler_fetch完成相关包的下载。 -- 如果想要下载的busybox包在本地用其他路径，比如busyboyy，则在busybox的bb文件或bbappend文件设定OPENEULER_LOCAL_NAME="busyboyy"，则在clone busybox时本地路径会变成busyboyy，注意,如果本地已经有busybox，但是依然设置了OPENEULER_LOCAL_NAME，则原本地仓将不会做任何操作，openeuler_fetch将直接新建一个busyboyy +- 如果想要下载的busybox包在本地用其他路径，比如busyboyy，则在busybox的bb文件或bbappend文件设定OPENEULER_LOCAL_NAME="busyboyy"，当clone busybox时本地路径会变成busyboyy。注意,如果本地已经有busybox，但是依然设置了OPENEULER_LOCAL_NAME，那么原本地仓将不会做任何操作，openeuler_fetch将直接新建一个busyboyy -- 如果在编译busybox中所依赖的某些文件不想要，而想要统一去除，则可以在bb文件或bbappend文件中设定OPENEULER_SRC_URI_REMOVE变量，比如busybox的SRC_URI中有https或git开头的文件路径，但是我们会自己下载而不需要系统默认设定的，则可以设置OPENEULER_SRC_URI_REMOVE="https git"，这样openeuler_fetch在处理时就会去除以https和git开头的文件 +- 如果在编译busybox中所依赖的某些文件不想要，想统一去除，则可以在bb文件或bbappend文件中设定OPENEULER_SRC_URI_REMOVE变量，比如busybox的SRC_URI中有https或git开头的文件路径，但是我们想自己下载而不需要系统默认设定的，则可以设置OPENEULER_SRC_URI_REMOVE="https git"，这样openeuler_fetch在处理时就会去除以https和git开头的文件 如何关闭openeuler_fetch功能 *************************** OPENEULER_FETCH有两种关闭方式： -1. 在meta-openeuler/conf/layer.conf中有一个全局变量OPENEULER_FETCH，该值默认设置为enable，即openeuler_fetch是开启状态，如果想要关闭openeuler_fetch则设置该值为disable， +1. 在meta-openeuler/conf/layer.conf中有一个全局变量OPENEULER_FETCH，该值默认为enable，即openeuler_fetch是开启状态，如果想要关闭openeuler_fetch，设置该值为disable即可。 -2. 在oebuild执行generate指令是将参数-df带上，也可以关闭openeuelr_fetch功能 +2. 在oebuild执行generate指令时，将参数-df带上，也可以关闭openeuelr_fetch功能 -另外 ``OPENEULER_FETCH`` 该值的作用域是全局的，我们在开发中可能会针对某一些或某几个包不需要运行openeuler_fetch，则可以在相关包的bb或bbappend中设定该值为disable \ No newline at end of file +另外 ``OPENEULER_FETCH`` 该值的作用域是全局的，我们在开发中可能会针对某一些包不需要运行openeuler_fetch，则可以在相关包的bb或bbappend中设定该值为disable \ No newline at end of file diff --git a/docs/source/develop_help/republish.rst b/docs/source/develop_help/republish.rst index 6bb936b2b94..11e4e92d16a 100644 --- a/docs/source/develop_help/republish.rst +++ b/docs/source/develop_help/republish.rst @@ -7,11 +7,11 @@ 1. 要求： - (1) 要求基于openEuler嵌入式代码工程制作，软件包可以随意裁剪增加。构建指导：https://openeuler.gitee.io/yocto-meta-openeuler/yocto/index.html + (1) 要求基于openEuler嵌入式代码工程制作，软件包可以随意裁剪增加。构建指导：https://openeuler.gitee.io/yocto-meta-openeuler/master/yocto/index.html 2. 建议： (1) 关键软件包版本（例如glib） 和配置（例如内核PAGE_SIZE大小） 和openEuler保持一致。 (2) 开发工具链推荐使用openEuler嵌入式官方发行版本。 - (3) 嵌入式特有安全加固规则（https://openeuler.gitee.io/yocto-meta-openeuler/security_hardening/index.html） 建议采用。 + (3) 采用嵌入式特有安全加固规则（https://openeuler.gitee.io/yocto-meta-openeuler/master/linux/security/index.html） 。 (4) 发行版提供面向具体行业的镜像文件（内核镜像和rootfs） 和开发工具链。 -- Gitee