标记样式指南¶

本页介绍了使用 reStructuredText（RST）标记语法编写 Blender 文档的约定。遵循这些约定可以确保文档的清晰度、一致性和易维护性。

一般约定¶

使用三空格缩进。
行长限制为 120 个字符。
按钮和菜单名称使用斜体。
除非绝对必要，否则避免使用 Unicode 字符。
应首选简单的句子结构，以便表达清晰。
避免使用冗长的文字（建议使用较短的段落和清晰的句子）。

标题¶

请使用以下标题层次结构：

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Note

每个 .rst 文件只应该有一个章节（chapter）标题（*）。
Parts 只应该用在目录和索引页面。

基本文本样式¶

整个文档中使用的通用文本样式：

*italic text*
**bold text**
``literal text`` (e.g., filenames, Python code snippets)

界面元素¶

界面元素的标准标记：

:kbd:`鼠标左键` -- 键盘和鼠标快捷键。
*Mirror* -- 界面标签（按钮、面板等）。
:menuselection:`3D 视图 --> 添加 --> 网格 --> 猴头` -- 通过菜单的导航路径。

列表¶

列表用于清晰地展示有次序的或分组的项目：

项目列表

- First item
- Second item
- Third item

编号列表：

#. First step
#. Second step
#. Third step

定义列表：

Term
   Definition text here.

有用的结构¶

|BLENDER_VERSION|：自动插入当前的 Blender 版本。
:abbr:`SSAO (Screen Space Ambient Occlusion)`：缩写，悬停时显示全文。
:term:`流形`：链接到词汇表中的相应条目。
:bl-icon:`icon_name`：将 Blender 图标包含为内联文本，详见图标中的完整列表。

交叉引用与链接¶

内部文档链接：

:doc:`Link Title </section/path/to/file>`

使用显式标签链接到特定章节：

.. _my-section-label:

Section Title
=============

Reference this section later with :ref:`Optional Title <my-section-label>`

同一文档内的隐式引用：

Section Title
=============

Reference it implicitly later using `Section Title`_

外部网站链接：

`Blender's Official Website <https://www.blender.org>`__

访问上下文相关手册¶

将 Blender UI 属性和操作符直接链接到手册入口：

右键单击 Blender 中的属性/操作符，选择 在线 Python 参考 获取 RNA 标记（显示在操作系统控制台中）。
在文档中，使用与 Blender RNA 标签相匹配的外部引用：

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid/obstacle regions.

对于操作符：

.. _bpy.ops.curve.subdivide:

Subdivide
=========

通过 “在线手册” 选项，Blender 使用这些标签将用户界面元素直接链接到文档条目。

Admonitions¶

Admonitions are special blocks used to highlight important notes, warnings, or additional information in the documentation.

Common admonition types include:

note
tip
important
warning
caution
seealso

Admonitions are created using the following markup:

.. note::

   This is a note for general information.

将 note 替换为上述列表中的所需类型，即可呈现其他类型。

图像¶

使用图示指令嵌入带标题的图像：

.. figure:: /images/interface_splash_current.png

   Splash screen of Blender.

截图准则¶

为确保截图的一致性：

使用 Blender 默认主题和设置。
缩放至最大级别（Ctrl-鼠标右键 或 小键盘加号）。
精确缩小八步（小键盘减号，按八次）。
如果适用，在内容周围留出大约 30 个像素的边距。

文件命名¶

请遵循以下图像文件命名准则：

Use lowercase letters, no spaces, underscores between sections, and dashes within multi-word sections.
只在 manual/images 目录中放置图像（无子文件夹）。

示例：

interface_splash_current.png
modeling_meshes_edit-mode.png

图像格式¶

.png：用于界面截图或纯色图像。
.jpg：用于色彩变化较大的拍摄图像或渲染图。
避免使用 .gif；而应使用嵌入式视频制作动画。

视频¶

嵌入托管在 Blender PeerTube 上的视频，网址是 video.blender.org。

.. peertube:: ID

ID 是从视频 URL 中提取的，例如：

https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c 的 ID 是 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c。

视频的准则¶

首选没有口语或文字性说明的视频，以便于翻译。
不要仅仅依靠视频来解释功能。手册文本本身应清楚地记录流程。

代码示例¶

代码片段应使用语法高亮和可选的行号：

.. code-block:: python
   :linenos:

   import bpy

   def example_function():
       print("Hello Blender")

占位符 & 编辑器注记¶

用于今后需要更新或完成的内容：

读者可见：

.. todo:: Complete this section when feature is finalized.

内部注记（读者不可见）：

.. Internal developer reminder goes here

扩展阅读¶

Sphinx RST 入门：RST 语法介绍。
Docutils reStructuredText 参考：有关 RST 标记的全面文档。