标记样式指南¶

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

约定¶

3空格缩进。
一行不应超过120个字符。
使用斜体字表示按钮/菜单名称。

其他宽松约定：

避免使用Unicode字符。
避免过多换行(比如，一句话占用一行)。

标题¶

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

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

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

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

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

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

Note

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

Note

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

文本样式¶

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

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

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

界面元素¶

:kbd:`LMB` ——键盘和鼠标快捷键。
*Mirror* —— 界面标签。
:menuselection:`3D View --> Add --> Mesh --> Monkey` ——菜单。

代码示例¶

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

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

图像¶

Figure标签用于放置图像:

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

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

准备好需要截图的区域，确保使用默认主题和设置。(有些情况下，你可能并不愿意使用默认设置，比如某些选项需在勾选复选框才能显现)
放大到最大缩放级别(按住 NumpadPlus 、 Ctrl-MMB 或类似方法)。
缩小8个缩放级别( NumpadMinus -- 8次)。
某些情况下，你可能想要在截取区域外有些留白。留白应该在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

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

视频¶

来自YouTube^™ 和Vimeo^™ 的视频可以使用嵌入

.. youtube:: ID

.. vimeo:: ID

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

https://www.youtube.com/watch?v=Ge2Kwy5EGE0 的ID为 Ge2Kwy5EGE0
http://vimeo.com/15837189 的ID为 15837189

使用指南¶

避免添加依赖声音的视频，因为这是很难翻译的。
不要嵌入视频教程作为解释功能的手段，文字本身应充分解释(尽管你可以在页面的底部使用 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>`__

目录布局¶

通用章节结构如下：

目录名称/
- 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 介绍该章节内容。

目录¶

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

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

延伸阅读¶

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

Sphinx RST入门: 不错的基础入门。
Docutils reStructuredText参考: 参考链接和用户文档。

Join the 2%

标记样式指南¶

约定¶

标题¶

文本样式¶

界面元素¶

代码示例¶

图像¶

文件¶

使用指南¶

视频¶

使用指南¶

有用的结构¶

交叉引用和链接¶

目录布局¶

目录¶

延伸阅读¶