标记样式指南

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

约定

  • 3空格缩进。

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

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

其他宽松约定:

  • 避免使用Unicode字符。

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

标题

  1. #################
  2. Document Part
  3. #################
  4. ****************
  5. Document Chapter
  6. ****************
  7. Document Section
  8. ================
  9. Document Subsection
  10. -------------------
  11. Document Subsubsection
  12. ^^^^^^^^^^^^^^^^^^^^^^
  13. Document Paragraph
  14. """"""""""""""""""

Note

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

Note

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

文本样式

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

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

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

界面元素

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

  • *Mirror* —— 界面标签。

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

代码示例

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

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

图像

Figure标签用于放置图像:

  1. .. figure:: /images/interface_window-system_splash_current.png
  2. 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

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

视频

视频可以嵌入Blender自托管的 “同行 <https://joinpeertube.org/>`__ 实例中,该实例可以在 “video.blender.org<https://video.blender.org/>`__ 中找到。使用以下指令嵌入视频:

  1. .. peertube:: ID

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

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

要上传新视频,请联系 “文档项目管理员 <https://developer.blender.org/project/view/53/>`__ 或将上传的视频包含在 补丁 说明中。

使用指南

  • 避免添加依赖于语音或单词的视频,因为这很难翻译。

  • 不要嵌入视频教程作为解释功能的手段,写作本身应该充分解释它。(尽管您可以在页面底部的 “教程” 标题下包含指向视频的链接)。

有用的结构

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

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

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

交叉引用和链接

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

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

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

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

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

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

链接到外部链接:

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

访问上下文相关手册

通过打开属性或操作者的上下文菜单(右键)并选择 在线手册 ,可以从Blender中链接到手册的特定部分。为了使其发挥作用,这需要在文档中加以说明。要将一个属性或操作符链接到手册的特定部分,你需要添加一个外部的手册,你需要添加一个外部参考链接标签,其ID与Blender的RNA标签匹配。找出一个属性的标签的最简单方法是,打开该属性/操作符的上下文菜单,选择 在线Python参考 ,从URL中提取标签。下面给出了一些在RST文件中的例子:

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

对于操作项:

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

扩展阅读

要了解更多关于reStructuredText的信息,请参阅:

‘狮身人面像 RST 入门 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`__

不错的基础入门。

“文档库” 重组文本参考 <https://docutils.sourceforge.io/rst.html>`__

参考链接和用户文档。