标记样式指南

本页涵盖了 reStructuredText (RST) 标记语言语法的写作和使用约定。

约定

  • 3空格缩进。

  • 一行不应超过120个字符。

  • 使用斜体字表示按钮/菜单名称。

其他宽松约定：

  • 避免使用Unicode字符。

  • 避免过多换行(比如，一句话占用一行)。

标题

  1. #################
  2.   Document Part
  3. #################
  5. ****************
  6. Document Chapter
  7. ****************
  9. Document Section
  10. ================
  12. Document Subsection
  13. -------------------
  15. Document Subsubsection
  16. ^^^^^^^^^^^^^^^^^^^^^^
  18. Document Paragraph
  19. """"""""""""""""""

Note

Parts 只应该用在内容和索引页面。

Note

每个 .rst 文件只应该有一个章节(chapter)标题(*)。

文本样式

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

以下是一些有用的文本样式标记:

  1. *italic*
  2. **bold**
  3. ``literal``

界面元素

  • :kbd:`LMB` ——键盘和鼠标快捷键。

  • *Mirror* —— 界面标签。

  • :menuselection:`3D视图 --> 添加网格 --> 网格 --> 猴头` ——菜单。

Operator Menus

Each operator should receive its own heading or page based on the length of the content. Each operator should have a reference admonition documenting the context of the operator:

  1. .. admonition:: Reference
  2.    :class: refbox
  4.    :Mode:      Edit Mode
  5.    :Menu:      :menuselection:`Curve --> Snap`
  6.    :Hotkey:    :kbd:`Shift-S`

Panels

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

  1. Panel Title
  2. ===========
  4. Nested Panel Title
  5. ------------------

Properties

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

  1. Property
  2.    Property description.
  4.    Hidden Property
  5.       Hidden property description.

Enum based menus should be documented using the following syntax:

  1. Menu Label
  2.    General description of the menu.
  4.    :Menu Item: Menu Item Definition.
  5.    :Menu Item: Menu Item Definition.
  6.    :Menu Item: Menu Item Definition.

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by right clicking on a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to right click on the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

  1. .. _bpy.types.FluidDomainSettings.use_fractions:
  3. Fractional Obstacles
  4.    Enables finer resolution in fluid / obstacle regions (second order obstacles)...
  6.    .. _bpy.types.FluidDomainSettings.fractions_distance:
  8.    Obstacle Distance
  9.       Determines how far apart fluid and obstacles are...

For an operator:

  1. .. _bpy.ops.curve.subdivide:
  3. Subdivide
  4. =========

代码示例

如果提供编程语言，支持代码高亮显示，使用 :linenos: 选项可以显示行号:

  1. .. code-block:: python
  2.    :linenos:
  4.    import bpy
  5.    def some_function():
  6.        ...

图像

Figure标签用于放置图像:

  1. .. figure:: /images/render_cycles_nodes_types_shaders_node.png
  3.    Image caption.

为了一致性，也因为这样有利于保证截图尺寸大小接近，编写手册需依照以下方式截屏：

  1. 准备好需要截图的区域，确保使用默认主题和设置。(有些情况下，你可能并不愿意使用默认设置，比如某些选项需在勾选复选框才能显现)

  2. 放大到最大缩放级别(按住 NumpadPlus 、 Ctrl-MMB 或类似方法)。

  3. 缩小8个缩放级别( NumpadMinus — 8次)。

  4. 某些情况下，你可能想要在截取区域外有些留白。留白应该在30px左右，但也没必要正好。

以上方法适用于用户界面的一些部分，但可能并不适用于所有情形。

文件

无大写，无空格

文件名小写，单词之间使用下划线。

有效排序

使用在文件名结尾添加标识符来顺序命名。

格式

对于纯色图片如blender界面截图，使用 .png 格式，而 .jpg 格式则用于色彩丰富的图片，如渲染样图和照片。

不要使用 .gif 文件，这些文件不便于维护，容易让人分散注意力，并且文件大小通常较大。如有必要，可以使用视频(参考下面的 Videos )。

位置

将文件放置于 manual/images 文件夹下，不要使用子文件夹。

命名

对于文件命名，使用下划线分隔章与节，名称包含2个或更多单词使用破折号分隔。所以，图像文件命名格式为 chapter_subsection_sub-subsection_id.png, 例如：

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

不要使用特殊字符或空格！

使用指南

  • 避免指定图像的分辨率，以便主题可以一致地处理图像，并跨不同屏幕尺寸提供最佳布局。

  • 在描述UI的面板或章节，最好是使用一张图片来显示所有相关区域(而不是每个图标或按钮一张图片)，并将其放置在你所编写章节的顶部，然后按照它们在图像中出现的顺序解释这些功能。

    Note

    手册可以长期维护是非常重要的，用户界面​​和工具选项在不断变化，所以要尽量避免使用过多图片(在不是特别必要的情况下)。否则这会造成过多的维护负担。

视频

Videos from YouTube™ can be embedded using:

  1. .. youtube:: ID

可以在视频的URL中找到视频 ID ，例如:

The ID for https://www.youtube.com/watch?v=Ge2Kwy5EGE0 is Ge2Kwy5EGE0.

使用指南

  • 避免添加依赖声音的视频，因为这是很难翻译的。

  • 不要嵌入视频教程作为解释功能的手段，文字本身应充分解释(尽管你可以在页面的底部使用 Tutorials 标题补充视频链接)。

有用的结构

  • |BLENDER_VERSION| ——解释当前手册适用的Blender版本。

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` ——向读者展示缩写的全称文本。

  • :term:`Manifold` —— 词汇表 入口链接。

交叉引用和链接

你可以链接到手册中另一个文档:

  1. :doc:`The Title </section/path/to/file>`

要链接到另一个文件(或者同一个)中的指定章节，可使用显式标签:

  1. .. _sample-label:
  3. [section or image to reference]
  5. Some text :ref:`Optional Title <sample-label>`

链接到同一文件中的标题:

  1. Titles are Targets
  2. ==================
  4. Body text.
  6. Implicit references, like `Titles are Targets`_

链接到外部链接:

  1. `Blender Website <https://www.blender.org>`__

目录布局

通用章节结构如下：

  • 目录名称/

    • index.rst (包含内部文件链接)

    • introduction.rst

    • section_1.rst

    • section_2.rst

例如：

  • rendering/

    • index.rst

    • cycles/

      • index.rst

      • introduction.rst

      • materials/

        • index.rst

        • introduction.rst

        • volumes.rst

这样做是为了将同一章节的内容包含在一个文件夹内。理想的情况下每个章节都应该有一个 index.rst (包含该章节目录)和一个 introduction.rst 介绍该章节内容。

目录

默认情况下，目录需显示两级深度:

  1. .. toctree::
  2.    :maxdepth: 2
  4.    introduction.rst
  5.    perspective.rst
  6.    depth_of_field.rst

延伸阅读

要了解更多关于reStructuredText的信息，请参阅：

Sphinx RST Primer

不错的基础入门。

Docutils reStructuredText Reference

参考链接和用户文档。