标记样式指南

    • 3空格缩进。

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

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

    其他宽松约定：

    • 避免使用Unicode字符。

    标题

    Note

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

    Note

    每个 文件只应该有一个章节(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 provides more insight additional constructs.

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

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

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

    • *Mirror* —— 界面标签。

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

    代码示例

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

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

    图像

    Figure标签用于放置图像:

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

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

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

    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

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

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

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

      Note

    Videos can be embedded from Blender’s self-hosted instance which can be found at video.blender.org. To embed a video using the following directive:

    1. .. peertube:: ID

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

    The ID for https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c is 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

    To get a new video uploaded, contact a or include the uploaded video in your Patch description.

    • Avoid adding videos that rely on voice or words, 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版本。

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

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

    交叉引用和链接

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

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

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

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

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

    链接到外部链接:

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

    It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of 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 open the context menu of 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:

    For an operator:

    1. .. _bpy.ops.curve.subdivide:

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

    Sphinx RST Primer

    不错的基础入门。

    参考链接和用户文档。