模板

The following guide provides patterns for interface elements and directories.

操作菜单

Each operator should receive its own heading or page based on the length of the content. At the start should be a reference admonition documenting the context of the operator:

  1. .. admonition:: Reference
  2.    :class: refbox
  4.    :Mode:      Edit Mode
  5.    :Menu:      :menuselection:`Curve --> Snap`
  6.    :Shortcut:  :kbd:`Shift-S`

面板

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

  1. Panel Title
  2. ===========
  4. Nested Panel Title
  5. ------------------

属性

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

  1. Property
  2.    Property description.
  4.    Hidden Property
  5.       Hidden property description.

Select menus should be documented using the following syntax:

  1. Menu Label
  2.    General description of the menu.
  4.    :Menu Item: Menu Item Definition.
  5.    :Menu Item: Menu Item Definition.
  6.    :Menu Item: Menu Item Definition.

节点

Nodes should always have three headings inputs, properties and outputs with a note of absence if the node has none. At the end of the page can be an optional example(s) section:

  1. **********
  2. World Node
  3. **********
  5. .. figure:: /images/render_shader-nodes_output_world_node.png
  6.    :align: right
  8.    The World node.
  10. Introduction and general use case(s).
  13. Inputs
  14. ======
  16. This node has no inputs.
  19. Properties
  20. ==========
  22. This node has no properties.
  25. Outputs
  26. =======
  28. This node has no outputs.
  31. Example
  32. =======

目录布局

通用章节结构如下：

  • 目录名称/

    • 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 介绍该章节内容。

目录

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

  1. .. toctree::
  2.    :maxdepth: 2
  4.    introduction.rst
  5.    perspective.rst
  6.    depth_of_field.rst