标记样式指南

    • 3空格缩进。

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

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

    其他宽松约定：

    • 避免使用Unicode字符。

    标题

    Note

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

    Note

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

    文本样式

    参考 ReStructured Text概述 ，查看如何为文档中的各种元素添加样式，以及如何添加列表、表格、图片和代码块。 提供了更多深入的其他结构。

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

    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:

    对于操作项:

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

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

    Sphinx RST Primer

    不错的基础入门。

    参考链接和用户文档。