标记样式指南

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

约定

  • 3空格缩进。

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

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

其他宽松约定：

  • 避免使用Unicode字符。

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

标题

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

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

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

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

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

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

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.

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

*italic*
**bold**
``literal``

界面元素

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

  • *Mirror* —— 界面标签。

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

代码示例

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

图像

Figure标签用于放置图像:

.. figure:: /images/interface_window-system_splash_current.png

   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 can be embedded from Blender's self-hosted PeerTube instance which can be found at video.blender.org. To embed a video using the following directive:

.. 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 Documentation Project Administrator 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_VERSION| ——解释当前手册适用的Blender版本。

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

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

交叉引用和链接

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

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

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

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

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

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

链接到外部链接:

`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:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

扩展阅读

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

Sphinx RST Primer

不错的基础入门。

Docutils reStructuredText Reference

参考链接和用户文档。