OpenRocket 文档贡献指南基于 Sphinx 的 reStructuredText 文档编辑、构建与风格规范全解【免费下载链接】openrocketModel-rocketry aerodynamics and trajectory simulation software项目地址: https://gitcode.com/GitHub_Trending/op/openrocket本文是 OpenRocket 开源项目的文档贡献技术指南系统讲解该项目为何采用 Sphinx 取代旧版 MediaWiki 搭建文档体系、如何在本地安装依赖并构建文档、以及整套 reStructuredText 写作风格规范标题层级、图片、超链接、Admonition、语义角色、替换文本、行宽与 ToDo 机制等。读完本文你将能够直接上手编辑 docs/source 目录下的 .rst 源文件本地构建出可浏览的 HTML 文档并写出与官方风格一致、可被 Sphinx 严格校验的文档内容。OpenRocket 文档风格指南中关于行宽换行的正确与错误示例图片来源docs/source/img/dev_guide/contributing_to_the_docs/Line-Wrapping.png为什么选择 Sphinx从 MediaWiki 到 Sphinx 的迁移背景OpenRocket 的文档体系经历过一次重要技术选型。早期项目使用 MediaWiki 维护文档但官方文档明确列出了转向 Sphinx 的五个核心理由更强大、现代、灵活Sphinx 支持比 MediaWiki 更复杂、更具交互性的文档结构能够承载从用户指南到开发者指南的多级内容体系更易维护文档以源码文件形式存在更新和管理都在版本控制中完成make html即可一键产出站点构建期校验Sphinx 在构建文档时会输出警告warnings和错误errors能主动暴露拼写、链接断裂、缩进错误等不一致问题——这是纯静态 wiki 无法提供的能力与代码同仓托管文档源文件与 OpenRocket 源码一起存放在仓库中资源集中、版本同步、天然获得 Git 版本控制能力贡献门槛降低此前部分贡献者访问 MediaWiki 的权限被阻断且长期无法解决迁移到基于 Git 仓库的 Sphinx 后任何人都可以通过 Pull Request 参与文档维护。Sphinx 以 reStructuredText简称 reST为主标记语言同时官方也支持 Markdown 与 LaTeX。对 OpenRocket 而言当前文档体系实际全部采用 .rst 源文件见 docs/source 目录。文档托管Read the Docs 与自动化构建OpenRocket 文档托管在 Read the Docs 平台。该平台从仓库源码自动构建文档并在线发布具备以下能力从 OpenRocket 仓库的源文件自动触发构建支持版本化查看——可为 OpenRocket 的不同版本分别构建并浏览对应文档内置站内搜索便于快速定位内容支持文档翻译扩大受众覆盖面。仓库根目录的 .readthedocs.yaml 给出了 Read the Docs 侧的构建配置包含三块关键信息构建系统使用 Ubuntu 22.04 与 Python 3.10通过requirements: docs/requirements.txt声明 Sphinx 依赖通过configuration: docs/source/conf.py指定 Sphinx 配置文件位置。这解释了为何文档构建只需要pip install与make html两条命令即可完成。编辑与构建文档从源码到 HTML 的完整流程编辑位置docs/source 目录所有文档源文件都位于仓库的docs/source目录下。该目录按内容类别组织docs/source/introduction项目概述、特性、贡献指南与 FAQdocs/source/setup安装、快速上手与偏好设置docs/source/user_guide面向用户的完整操作指南docs/source/dev_guide面向开发者的指南本文对应的contributing_to_the_docs.rst即位于此docs/source/img文档图片资源目录结构与对应 .rst 源文件保持一致docs/source/conf.pySphinx 构建配置文件docs/source/index.rst文档首页通过toctree指令汇总全部章节Introduction、Setup、User Guide、Developer Guide 四大板块。文档的整体入口结构可查看 docs/source/index.rst每个板块对应一个toctree例如 Developer Guide 板块中列出了dev_guide/contributing_to_the_docs等全部开发者文档页。新增文档页面后需要把它登记到对应的toctree中才能出现在导航与索引里。第一步安装依赖在docs目录下打开终端执行pip install -r requirements.txtdocs/requirements.txt 中的依赖项如下sphinx sphinx-rtd-theme sphinx-rtd-dark-mode sphinx_new_tab_link其中sphinx是文档构建核心sphinx-rtd-theme是 OpenRocket 使用的 Read the Docs 主题在 conf.py 中通过html_theme sphinx_rtd_theme指定sphinx-rtd-dark-mode提供暗色模式切换conf.py 中default_dark_mode False表示用户默认以浅色模式打开sphinx_new_tab_link让外链在新标签页打开。第二步构建 HTML在docs目录下执行make html构建产物生成在docs/build/html目录。用浏览器打开其中的index.html即可预览完整文档站点。Linux/macOS 下的构建入口是 docs/Makefile它定义了SPHINXBUILD ? sphinx-build、SOURCEDIR source、BUILDDIR build三个核心变量并通过sphinx-build -M $ $(SOURCEDIR) $(BUILDDIR)的 catch-all 规则将所有目标html、clean 等转发给 Sphinx。Windows 用户则可使用同目录下的 docs/make.bat它等效封装了sphinx-build -M target的调用并会在缺少sphinx-build命令时给出明确提示。第三步清理构建产物当修改了主题或其他构建配置时需要清理旧的构建缓存make clean这一步骤之所以必要是因为 Sphinx 会缓存部分构建中间产物不清除可能导致旧主题样式或过时输出残留。构建配置速览conf.py 的关键设置docs/source/conf.py 是 Sphinx 构建行为的总开关与本文写作直接相关的关键配置包括配置项当前取值含义projectOpenRocket文档项目名称release23.09当前文档对应的 OpenRocket 版本extensionssphinx.ext.duration、sphinx.ext.todo、sphinx_new_tab_link、sphinx_rtd_dark_mode启用的 Sphinx 扩展其中sphinx.ext.todo支撑下文介绍的 ToDo 指令html_themesphinx_rtd_themeHTML 主题html_static_path[_static]静态资源目录配合 docs/source/_static/custom.css 定制主题外观如导航栏配色、提示框图标等todo_include_todosFalse是否在输出中显示 ToDo 列表rst_prolog定义\|java_vers\|等替换文本全局可用的 reST 替换符风格指南OpenRocket 文档的写作规范以下规范来自 docs/source/dev_guide/contributing_to_the_docs.rst是向该仓库提交文档时必须遵守的约定。标题层级Heading LevelsreStructuredText 本身并不规定哪个字符对应哪一级标题——文档结构由标题的先后顺序推导。但 OpenRocket 文档明确约定了统一的层级规则保证多篇文档之间风格一致层级修饰字符用途H1Parts#加顶线overline分部标题当前基本未使用H2Chapters*加顶线章标题即页面标题H3Sections节标题H4Subsections-小节标题H5Subsubsections^子小节标题H6Paragraphs段落级标题一个重要的硬性要求顶线和下划线的长度必须与标题文本完全一致。示例***************************************** H1: This is a chapter (title of the page) ***************************************** H2: This is a section H3: This is a subsection ------------------------ H4: This is a subsubsection ^^^^^^^^^^^^^^^^^^^^^^^^^^^ H5: This is a paragraph 对照 docs/source/dev_guide/contributing_to_the_docs.rst 第 1-3 行可以看到页面标题正是使用*加顶线的章标题写法。水平分隔线Horizontal Rules水平分隔线用于切分文档中的不同大节由四个或更多连字符----构成This is a section ---- This is another section 风格指南建议在开始新的大节H2 级别之前始终添加一条水平分隔线。这与 reST 的一个易混淆点相关——当标题下方紧跟一行短横线时Sphinx 可能将其解析为其他语法用足够长度的----明确分隔可以避免这类问题。实际文档中每个大节之间都用----分隔。添加图片Adding Images图片通过figure指令插入推荐格式为 PNG、JPEG 或 SVG。标准写法如下.. figure:: /img/path/to/your/image.png :width: 50% (please always express this as a percentage, and dont go over 95% width) :align: left, center, or right (center should be used in general) :alt: Alternative text :figclass: or-image-border (optional, for custom styling) This is the caption of the image.要点归纳:width:必须用百分比表示且不要超过 95%:align:一般为center:alt:提供替代文本服务无障碍访问与搜索引擎:figclass:为可选参数or-image-border用于套用自定义边框样式图片统一存放在docs/source/img目录子目录结构与引用该图片的 .rst 文件路径保持一致。例如要为docs/source/user_guide/quick_start.rst配图图片应放在docs/source/img/user_guide/quick_start/。OpenRocket 文档实际使用的示例图片位于 docs/source/img/dev_guide/contributing_to_the_docs其中Line-Wrapping.png用于说明行宽换行规范。超链接Hyperlinks外部链接采用\文本 __ 的双下划线形式link text www.your_url.com__warning结尾必须使用双下划线__。如果使用单下划线当文档中出现多个相同文本的链接时会产生解析冲突。站内页面链接使用:doc:角色:doc:link text /path/to/your/page站内锚点链接使用:ref:角色配合自定义锚点:ref:link text Link anchor锚点通过如下方式在目标位置定义.. _Link anchor: This is the place you want to link to.以本文档为例文中的:ref:Heading levels heading_levels 正是跳转到上文标题层级一节的锚点链接锚点定义于.. _heading_levels:。Admonition 提示框Tip、Note、Warning、Attention、See AlsoreStructuredText 提供丰富的提示框指令OpenRocket 支持的类型有attention、caution、danger、error、hint、important、note、tip、warning。文档中最常用的四类是.. tip:: This is a tip... note:: This is a note... warning:: This is a warning... attention:: This is an attention.此外还有seealso指令用于推荐关联阅读页面.. seealso:: See also the following page: :doc:Development Overview /dev_guide/development_overview在实际文档中seealso常被用来串联开发者指南中的相邻主题例如从文档贡献指南跳转到 docs/source/dev_guide/development_overview.rst对应 docs/source/index.rst 中的 Development Overview 页面。语义标记Sphinx 解释文本角色RolesSphinx 通过解释文本角色interpreted text roles为文字赋予语义写法为:rolename:contentSphinx 会按语义进行相应渲染。OpenRocket 文档中最常用的五个角色:menuselection:——表示用户界面中的菜单选择序列箭头必须使用--:menuselection:File -- Open example:command:——表示命令行中可执行的命令To list the contents of a directory, use the :command:ls command.:file:——表示文件或文件路径Open the configuration file :file:conf.py to modify the settings.:kbd:——表示键盘按键或快捷键Press :kbd:Ctrl :kbd:C to copy the text.:guilabel:——表示 GUI 元素按钮、标签、输入框等的文案Click the :guilabel:Submit button to save your changes.这五个角色在文档中广泛使用例如 docs/source/dev_guide/development_setup.rst 中对 Fork 按钮的描述就使用了:guilabel:角色。正确使用角色不仅能统一渲染样式还能让文档在语义上可被工具链检索与校验。缩写Abbreviations使用:abbr:角色定义缩写鼠标悬停时可显示完整文本:abbr:OR (OpenRocket) is a very awesome tool!替换文本SubstitutionsSphinx 允许定义替换符用于替换文档中频繁出现且易变的文本如版本号、日期。自定义替换符统一定义在 docs/source/conf.py 的rst_prolog段中。当前仓库定义了两个替换符rst_prolog .. |java_vers| replace:: 17 .. |br_no_pad| raw:: html div styleline-height: 0; padding: 0; margin: 0/div 其中|java_vers|表示 OpenRocket 要求的 Java 版本当前为 17。在正文中使用方式为OpenRocket uses Java |java_vers| (Java |java_vers|).由于|java_vers|在构建时被替换为17当 Java 版本升级时只需修改conf.py一处所有引用点自动同步更新——这正是替换文本的价值所在。在 docs/source/dev_guide/development_setup.rst 中即可看到Java |java_vers|的实际用法。特殊字符转义Escaping Special Characters当正文中需要出现会被 Sphinx/reST 特殊解释的字符时用反斜杠转义反斜杠本身写为\\冒号写为\:。例如本文中讲解角色语法时\:menuselection\:的写法就是在转义冒号避免被误解析为角色起始符。行宽与换行Line Wrapping规则.rst 源文件的单行长度尽量控制在 ±120 个字符以内。这样做的好处是源码更易阅读代码块无需横向滚动。核心机制如果两行文本之间没有空行它们会被渲染为同一个段落。因此可以在任意位置自由换行只要不插入空行即可保持段落连续。列表项的换行必须遵循缩进规则——续行的缩进空格数必须与列表项第一行一致否则构建时会触发编译警告。正确与错误写法对照- This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple lines.缩进错误会导致 Sphinx 在构建时输出 warning因此这也是构建期校验优势的一个具体体现。ToDo 机制标记未完成的文档段落如果某段文档尚未完成可以插入todo指令作为待办标记.. todo:: This section is not yet finished. Please come back later to complete it.默认情况下 ToDo 不会显示在构建输出中——conf.py 中todo_include_todos False。当你希望查看全站所有 ToDo 时把该选项改为True并重新构建文档页面中会列出全部待办条目对应todolist指令的输出。这一机制依赖 conf.py 中启用的sphinx.ext.todo扩展。如何提交你的文档贡献完成文档修改后通过 Pull Request 提交给 OpenRocket 维护团队。具体步骤参考 docs/source/dev_guide/development_setup.rst 中的 Obtaining the Source Code 一节先 Fork 官方仓库再克隆到本地在docs/source目录下修改或新增 .rst 文件按本文风格规范写作在docs目录依次执行pip install -r requirements.txt与make html本地验证构建无警告提交 Pull Request 描述你的改动。如果你暂时不想搭建完整开发环境也可以直接提交 Issue 附上拟议的文档改动由维护团队协助落地。小结OpenRocket 选择 Sphinx Read the Docs 搭建文档体系核心收益在于文档即源码贡献者通过 Pull Request 即可参与构建期能自动暴露语法与一致性问题版本控制与代码同步。本文覆盖了从依赖安装、make html构建、make clean清理到标题层级、分隔线、图片、链接、Admonition、语义角色、替换文本、转义、行宽与 ToDo 的完整写作规范。建议在动手编辑前完整通读 docs/source/dev_guide/contributing_to_the_docs.rst 原文、docs/source/conf.py 配置与 docs/source/index.rst 目录结构并在本地构建验证后再提交即可成为合格的 OpenRocket 文档贡献者。【免费下载链接】openrocketModel-rocketry aerodynamics and trajectory simulation software项目地址: https://gitcode.com/GitHub_Trending/op/openrocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
OpenRocket 文档贡献指南基于 Sphinx 的 reStructuredText 文档编辑、构建与风格规范全解【免费下载链接】openrocketModel-rocketry aerodynamics and trajectory simulation software项目地址: https://gitcode.com/GitHub_Trending/op/openrocket本文是 OpenRocket 开源项目的文档贡献技术指南系统讲解该项目为何采用 Sphinx 取代旧版 MediaWiki 搭建文档体系、如何在本地安装依赖并构建文档、以及整套 reStructuredText 写作风格规范标题层级、图片、超链接、Admonition、语义角色、替换文本、行宽与 ToDo 机制等。读完本文你将能够直接上手编辑 docs/source 目录下的 .rst 源文件本地构建出可浏览的 HTML 文档并写出与官方风格一致、可被 Sphinx 严格校验的文档内容。OpenRocket 文档风格指南中关于行宽换行的正确与错误示例图片来源docs/source/img/dev_guide/contributing_to_the_docs/Line-Wrapping.png为什么选择 Sphinx从 MediaWiki 到 Sphinx 的迁移背景OpenRocket 的文档体系经历过一次重要技术选型。早期项目使用 MediaWiki 维护文档但官方文档明确列出了转向 Sphinx 的五个核心理由更强大、现代、灵活Sphinx 支持比 MediaWiki 更复杂、更具交互性的文档结构能够承载从用户指南到开发者指南的多级内容体系更易维护文档以源码文件形式存在更新和管理都在版本控制中完成make html即可一键产出站点构建期校验Sphinx 在构建文档时会输出警告warnings和错误errors能主动暴露拼写、链接断裂、缩进错误等不一致问题——这是纯静态 wiki 无法提供的能力与代码同仓托管文档源文件与 OpenRocket 源码一起存放在仓库中资源集中、版本同步、天然获得 Git 版本控制能力贡献门槛降低此前部分贡献者访问 MediaWiki 的权限被阻断且长期无法解决迁移到基于 Git 仓库的 Sphinx 后任何人都可以通过 Pull Request 参与文档维护。Sphinx 以 reStructuredText简称 reST为主标记语言同时官方也支持 Markdown 与 LaTeX。对 OpenRocket 而言当前文档体系实际全部采用 .rst 源文件见 docs/source 目录。文档托管Read the Docs 与自动化构建OpenRocket 文档托管在 Read the Docs 平台。该平台从仓库源码自动构建文档并在线发布具备以下能力从 OpenRocket 仓库的源文件自动触发构建支持版本化查看——可为 OpenRocket 的不同版本分别构建并浏览对应文档内置站内搜索便于快速定位内容支持文档翻译扩大受众覆盖面。仓库根目录的 .readthedocs.yaml 给出了 Read the Docs 侧的构建配置包含三块关键信息构建系统使用 Ubuntu 22.04 与 Python 3.10通过requirements: docs/requirements.txt声明 Sphinx 依赖通过configuration: docs/source/conf.py指定 Sphinx 配置文件位置。这解释了为何文档构建只需要pip install与make html两条命令即可完成。编辑与构建文档从源码到 HTML 的完整流程编辑位置docs/source 目录所有文档源文件都位于仓库的docs/source目录下。该目录按内容类别组织docs/source/introduction项目概述、特性、贡献指南与 FAQdocs/source/setup安装、快速上手与偏好设置docs/source/user_guide面向用户的完整操作指南docs/source/dev_guide面向开发者的指南本文对应的contributing_to_the_docs.rst即位于此docs/source/img文档图片资源目录结构与对应 .rst 源文件保持一致docs/source/conf.pySphinx 构建配置文件docs/source/index.rst文档首页通过toctree指令汇总全部章节Introduction、Setup、User Guide、Developer Guide 四大板块。文档的整体入口结构可查看 docs/source/index.rst每个板块对应一个toctree例如 Developer Guide 板块中列出了dev_guide/contributing_to_the_docs等全部开发者文档页。新增文档页面后需要把它登记到对应的toctree中才能出现在导航与索引里。第一步安装依赖在docs目录下打开终端执行pip install -r requirements.txtdocs/requirements.txt 中的依赖项如下sphinx sphinx-rtd-theme sphinx-rtd-dark-mode sphinx_new_tab_link其中sphinx是文档构建核心sphinx-rtd-theme是 OpenRocket 使用的 Read the Docs 主题在 conf.py 中通过html_theme sphinx_rtd_theme指定sphinx-rtd-dark-mode提供暗色模式切换conf.py 中default_dark_mode False表示用户默认以浅色模式打开sphinx_new_tab_link让外链在新标签页打开。第二步构建 HTML在docs目录下执行make html构建产物生成在docs/build/html目录。用浏览器打开其中的index.html即可预览完整文档站点。Linux/macOS 下的构建入口是 docs/Makefile它定义了SPHINXBUILD ? sphinx-build、SOURCEDIR source、BUILDDIR build三个核心变量并通过sphinx-build -M $ $(SOURCEDIR) $(BUILDDIR)的 catch-all 规则将所有目标html、clean 等转发给 Sphinx。Windows 用户则可使用同目录下的 docs/make.bat它等效封装了sphinx-build -M target的调用并会在缺少sphinx-build命令时给出明确提示。第三步清理构建产物当修改了主题或其他构建配置时需要清理旧的构建缓存make clean这一步骤之所以必要是因为 Sphinx 会缓存部分构建中间产物不清除可能导致旧主题样式或过时输出残留。构建配置速览conf.py 的关键设置docs/source/conf.py 是 Sphinx 构建行为的总开关与本文写作直接相关的关键配置包括配置项当前取值含义projectOpenRocket文档项目名称release23.09当前文档对应的 OpenRocket 版本extensionssphinx.ext.duration、sphinx.ext.todo、sphinx_new_tab_link、sphinx_rtd_dark_mode启用的 Sphinx 扩展其中sphinx.ext.todo支撑下文介绍的 ToDo 指令html_themesphinx_rtd_themeHTML 主题html_static_path[_static]静态资源目录配合 docs/source/_static/custom.css 定制主题外观如导航栏配色、提示框图标等todo_include_todosFalse是否在输出中显示 ToDo 列表rst_prolog定义\|java_vers\|等替换文本全局可用的 reST 替换符风格指南OpenRocket 文档的写作规范以下规范来自 docs/source/dev_guide/contributing_to_the_docs.rst是向该仓库提交文档时必须遵守的约定。标题层级Heading LevelsreStructuredText 本身并不规定哪个字符对应哪一级标题——文档结构由标题的先后顺序推导。但 OpenRocket 文档明确约定了统一的层级规则保证多篇文档之间风格一致层级修饰字符用途H1Parts#加顶线overline分部标题当前基本未使用H2Chapters*加顶线章标题即页面标题H3Sections节标题H4Subsections-小节标题H5Subsubsections^子小节标题H6Paragraphs段落级标题一个重要的硬性要求顶线和下划线的长度必须与标题文本完全一致。示例***************************************** H1: This is a chapter (title of the page) ***************************************** H2: This is a section H3: This is a subsection ------------------------ H4: This is a subsubsection ^^^^^^^^^^^^^^^^^^^^^^^^^^^ H5: This is a paragraph 对照 docs/source/dev_guide/contributing_to_the_docs.rst 第 1-3 行可以看到页面标题正是使用*加顶线的章标题写法。水平分隔线Horizontal Rules水平分隔线用于切分文档中的不同大节由四个或更多连字符----构成This is a section ---- This is another section 风格指南建议在开始新的大节H2 级别之前始终添加一条水平分隔线。这与 reST 的一个易混淆点相关——当标题下方紧跟一行短横线时Sphinx 可能将其解析为其他语法用足够长度的----明确分隔可以避免这类问题。实际文档中每个大节之间都用----分隔。添加图片Adding Images图片通过figure指令插入推荐格式为 PNG、JPEG 或 SVG。标准写法如下.. figure:: /img/path/to/your/image.png :width: 50% (please always express this as a percentage, and dont go over 95% width) :align: left, center, or right (center should be used in general) :alt: Alternative text :figclass: or-image-border (optional, for custom styling) This is the caption of the image.要点归纳:width:必须用百分比表示且不要超过 95%:align:一般为center:alt:提供替代文本服务无障碍访问与搜索引擎:figclass:为可选参数or-image-border用于套用自定义边框样式图片统一存放在docs/source/img目录子目录结构与引用该图片的 .rst 文件路径保持一致。例如要为docs/source/user_guide/quick_start.rst配图图片应放在docs/source/img/user_guide/quick_start/。OpenRocket 文档实际使用的示例图片位于 docs/source/img/dev_guide/contributing_to_the_docs其中Line-Wrapping.png用于说明行宽换行规范。超链接Hyperlinks外部链接采用\文本 __ 的双下划线形式link text www.your_url.com__warning结尾必须使用双下划线__。如果使用单下划线当文档中出现多个相同文本的链接时会产生解析冲突。站内页面链接使用:doc:角色:doc:link text /path/to/your/page站内锚点链接使用:ref:角色配合自定义锚点:ref:link text Link anchor锚点通过如下方式在目标位置定义.. _Link anchor: This is the place you want to link to.以本文档为例文中的:ref:Heading levels heading_levels 正是跳转到上文标题层级一节的锚点链接锚点定义于.. _heading_levels:。Admonition 提示框Tip、Note、Warning、Attention、See AlsoreStructuredText 提供丰富的提示框指令OpenRocket 支持的类型有attention、caution、danger、error、hint、important、note、tip、warning。文档中最常用的四类是.. tip:: This is a tip... note:: This is a note... warning:: This is a warning... attention:: This is an attention.此外还有seealso指令用于推荐关联阅读页面.. seealso:: See also the following page: :doc:Development Overview /dev_guide/development_overview在实际文档中seealso常被用来串联开发者指南中的相邻主题例如从文档贡献指南跳转到 docs/source/dev_guide/development_overview.rst对应 docs/source/index.rst 中的 Development Overview 页面。语义标记Sphinx 解释文本角色RolesSphinx 通过解释文本角色interpreted text roles为文字赋予语义写法为:rolename:contentSphinx 会按语义进行相应渲染。OpenRocket 文档中最常用的五个角色:menuselection:——表示用户界面中的菜单选择序列箭头必须使用--:menuselection:File -- Open example:command:——表示命令行中可执行的命令To list the contents of a directory, use the :command:ls command.:file:——表示文件或文件路径Open the configuration file :file:conf.py to modify the settings.:kbd:——表示键盘按键或快捷键Press :kbd:Ctrl :kbd:C to copy the text.:guilabel:——表示 GUI 元素按钮、标签、输入框等的文案Click the :guilabel:Submit button to save your changes.这五个角色在文档中广泛使用例如 docs/source/dev_guide/development_setup.rst 中对 Fork 按钮的描述就使用了:guilabel:角色。正确使用角色不仅能统一渲染样式还能让文档在语义上可被工具链检索与校验。缩写Abbreviations使用:abbr:角色定义缩写鼠标悬停时可显示完整文本:abbr:OR (OpenRocket) is a very awesome tool!替换文本SubstitutionsSphinx 允许定义替换符用于替换文档中频繁出现且易变的文本如版本号、日期。自定义替换符统一定义在 docs/source/conf.py 的rst_prolog段中。当前仓库定义了两个替换符rst_prolog .. |java_vers| replace:: 17 .. |br_no_pad| raw:: html div styleline-height: 0; padding: 0; margin: 0/div 其中|java_vers|表示 OpenRocket 要求的 Java 版本当前为 17。在正文中使用方式为OpenRocket uses Java |java_vers| (Java |java_vers|).由于|java_vers|在构建时被替换为17当 Java 版本升级时只需修改conf.py一处所有引用点自动同步更新——这正是替换文本的价值所在。在 docs/source/dev_guide/development_setup.rst 中即可看到Java |java_vers|的实际用法。特殊字符转义Escaping Special Characters当正文中需要出现会被 Sphinx/reST 特殊解释的字符时用反斜杠转义反斜杠本身写为\\冒号写为\:。例如本文中讲解角色语法时\:menuselection\:的写法就是在转义冒号避免被误解析为角色起始符。行宽与换行Line Wrapping规则.rst 源文件的单行长度尽量控制在 ±120 个字符以内。这样做的好处是源码更易阅读代码块无需横向滚动。核心机制如果两行文本之间没有空行它们会被渲染为同一个段落。因此可以在任意位置自由换行只要不插入空行即可保持段落连续。列表项的换行必须遵循缩进规则——续行的缩进空格数必须与列表项第一行一致否则构建时会触发编译警告。正确与错误写法对照- This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple lines. This is a list item that is broken up into multiple lines.缩进错误会导致 Sphinx 在构建时输出 warning因此这也是构建期校验优势的一个具体体现。ToDo 机制标记未完成的文档段落如果某段文档尚未完成可以插入todo指令作为待办标记.. todo:: This section is not yet finished. Please come back later to complete it.默认情况下 ToDo 不会显示在构建输出中——conf.py 中todo_include_todos False。当你希望查看全站所有 ToDo 时把该选项改为True并重新构建文档页面中会列出全部待办条目对应todolist指令的输出。这一机制依赖 conf.py 中启用的sphinx.ext.todo扩展。如何提交你的文档贡献完成文档修改后通过 Pull Request 提交给 OpenRocket 维护团队。具体步骤参考 docs/source/dev_guide/development_setup.rst 中的 Obtaining the Source Code 一节先 Fork 官方仓库再克隆到本地在docs/source目录下修改或新增 .rst 文件按本文风格规范写作在docs目录依次执行pip install -r requirements.txt与make html本地验证构建无警告提交 Pull Request 描述你的改动。如果你暂时不想搭建完整开发环境也可以直接提交 Issue 附上拟议的文档改动由维护团队协助落地。小结OpenRocket 选择 Sphinx Read the Docs 搭建文档体系核心收益在于文档即源码贡献者通过 Pull Request 即可参与构建期能自动暴露语法与一致性问题版本控制与代码同步。本文覆盖了从依赖安装、make html构建、make clean清理到标题层级、分隔线、图片、链接、Admonition、语义角色、替换文本、转义、行宽与 ToDo 的完整写作规范。建议在动手编辑前完整通读 docs/source/dev_guide/contributing_to_the_docs.rst 原文、docs/source/conf.py 配置与 docs/source/index.rst 目录结构并在本地构建验证后再提交即可成为合格的 OpenRocket 文档贡献者。【免费下载链接】openrocketModel-rocketry aerodynamics and trajectory simulation software项目地址: https://gitcode.com/GitHub_Trending/op/openrocket创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
