标记样式指南¶
本页涵盖了 reStructuredText (RST) 标记语言语法的写作和使用约定。
标题¶
#################
Document Part
#################
****************
Document Chapter
****************
Document Section
================
Document Subsection
-------------------
Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^
Document Paragraph
""""""""""""""""""
Note
Parts 只应该用在内容和索引页面。
Note
每个 .rst 文件只应该有一个章节（chapter）标题（*）。
文本样式¶
参考 ReStructured Text概述 ，查看如何为文档中的各种元素添加样式，以及如何添加列表、表格、图片和代码块。 sphinx参考 提供了更多深入的其他结构。
以下是一些有用的文本样式标记:
*italic*
**bold**
``literal``
界面元素¶
:kbd:`LMB`——键盘和鼠标快捷键。*Mirror*—— 界面标签。:menuselection:`3D视图 --> 添加网格 --> 网格 --> 猴头`——菜单。
代码示例¶
如果提供编程语言，支持代码高亮显示，使用 :linenos: 选项可以显示行号:
.. code-block:: python
:linenos:
import bpy
def some_function():
...
图像¶
Figure标签用于放置图像:
.. figure:: /images/interface_window-system_splash_current.png
Image caption.
为了一致性，也因为这样有利于保证截图尺寸大小接近，编写手册需依照以下方式截屏：
准备好需要截图的区域，确保使用默认主题和设置。（有些情况下，你可能并不愿意使用默认设置，比如某些选项需在勾选复选框才能显现）
放大到最大缩放级别（按住 NumpadPlus 、 Ctrl-MMB 或类似方法）。
缩小8个缩放级别（ NumpadMinus -- 8次）。
某些情况下，你可能想要在截取区域外有些留白。留白应该在30px左右，但也没必要正好。
以上方法适用于用户界面的一些部分，但可能并不适用于所有情形。
文件¶
- 无大写，无空格
文件名小写，单词之间使用下划线。
- 有效排序
使用在文件名结尾添加标识符来顺序命名。
- 格式
对于纯色图片如blender界面截图，使用
.png格式，而.jpg格式则用于色彩丰富的图片，如渲染样图和照片。不要使用
.gif文件，这些文件不便于维护，容易让人分散注意力，并且文件大小通常较大。如有必要，可以使用视频（参考下面的 Videos ）。- 位置
将文件放置于
manual/images文件夹下，不要使用子文件夹。- 命名
对于文件命名，使用下划线分隔章与节，名称包含2个或更多单词使用破折号分隔。所以，图像文件命名格式为
chapter_subsection_sub-subsection_id.png, 例如：interface_splash_current.pnginterface_undo-redo_last.pnginterface_undo-redo_repeat-history-menu.png
不要使用特殊字符或空格！
使用指南¶
避免指定图像的分辨率，以便主题可以一致地处理图像，并跨不同屏幕尺寸提供最佳布局。
在描述UI的面板或章节，最好是使用一张图片来显示所有相关区域（而不是每个图标或按钮一张图片），并将其放置在你所编写章节的顶部，然后按照它们在图像中出现的顺序解释这些功能。
Note
手册可以长期维护是非常重要的，用户界面和工具选项在不断变化，所以要尽量避免使用过多图片（在不是特别必要的情况下）。否则这会造成过多的维护负担。
视频¶
Videos from YouTube™ can be embedded using:
.. youtube:: ID
可以在视频的URL中找到视频 ID ，例如:
The ID for https://www.youtube.com/watch?v=Ge2Kwy5EGE0 is Ge2Kwy5EGE0.
使用指南¶
Avoid adding videos that rely on voice, as this is difficult to translate.
Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately (though you may include a link to the video at the bottom of the page under the heading
Tutorials).
有用的结构¶
|BLENDER_VERSION|——解释当前手册适用的Blender版本。:abbr:`SSAO (Screen Space Ambient Occlusion)`——向读者展示缩写的全称文本。:term:`Manifold`—— 词汇表 入口链接。
交叉引用和链接¶
你可以链接到手册中另一个文档:
:doc:`The Title </section/path/to/file>`
要链接到另一个文件（或者同一个）中的指定章节，可使用显式标签:
.. _sample-label:
[section or image to reference]
Some text :ref:`Optional Title <sample-label>`
链接到同一文件中的标题:
Titles are Targets
==================
Body text.
Implicit references, like `Titles are Targets`_
链接到外部链接:
`Blender Website <https://www.blender.org>`__
访问上下文相关手册¶
通过打开属性或操作者的上下文菜单（右键）并选择 在线手册 ，可以从Blender中链接到手册的特定部分。为了使其发挥作用，这需要在文档中加以说明。要将一个属性或操作符链接到手册的特定部分，你需要添加一个外部的手册，你需要添加一个外部参考链接标签，其ID与Blender的RNA标签匹配。找出一个属性的标签的最简单方法是，打开该属性/操作符的上下文菜单，选择 在线Python参考 ，从URL中提取标签。下面给出了一些在RST文件中的例子:
.. _bpy.types.FluidDomainSettings.use_fractions:
Fractional Obstacles
Enables finer resolution in fluid / obstacle regions (second order obstacles)...
.. _bpy.types.FluidDomainSettings.fractions_distance:
Obstacle Distance
Determines how far apart fluid and obstacles are...
对于操作项:
.. _bpy.ops.curve.subdivide:
Subdivide
=========
扩展阅读¶
要了解更多关于reStructuredText的信息，请参阅：
- '狮身人面像 RST 入门 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__
不错的基础入门。
- "文档库" 重组文本参考 <https://docutils.sourceforge.io/rst.html>`__
参考链接和用户文档。