[Bf-docboard-svn] bf-manual: [8049] branches/blender-2.93-release/blender_docs/manual/about: about: split markup guide
Tobias Heinke
noreply at blender.org
Thu May 20 01:58:20 CEST 2021
Revision: 8049
https://developer.blender.org/rBM8049
Author: TobiasH
Date: 2021-05-20 01:58:20 +0200 (Thu, 20 May 2021)
Log Message:
-----------
about: split markup guide
Differential Revision: https://developer.blender.org/D11316
Modified Paths:
--------------
branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/markup_guide.rst
branches/blender-2.93-release/blender_docs/manual/about/contribute/index.rst
branches/blender-2.93-release/blender_docs/manual/about/index.rst
Added Paths:
-----------
branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/templates.rst
Modified: branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/markup_guide.rst
===================================================================
--- branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/markup_guide.rst 2021-05-19 23:32:03 UTC (rev 8048)
+++ branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/markup_guide.rst 2021-05-19 23:58:20 UTC (rev 8049)
@@ -90,86 +90,6 @@
- ``:menuselection:`3D Viewport --> Add --> Mesh --> Monkey``` -- menus.
-Operator Menus
---------------
-
-Each operator should receive its own heading or page based on the length of the content.
-Each operator should have a reference admonition documenting the context of the operator::
-
- .. admonition:: Reference
- :class: refbox
-
- :Mode: Edit Mode
- :Menu: :menuselection:`Curve --> Snap`
- :Shortcut: :kbd:`Shift-S`
-
-
-Panels
-------
-
-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::
-
- Panel Title
- ===========
-
- Nested Panel Title
- ------------------
-
-
-Properties
-----------
-
-Properties should be documented using definition lists.
-Properties that are hidden based on other properties should used nested definitions::
-
- Property
- Property description.
-
- Hidden Property
- Hidden property description.
-
-Enum based menus should be documented using the following syntax::
-
- Menu Label
- General description of the menu.
-
- :Menu Item: Menu Item Definition.
- :Menu Item: Menu Item Definition.
- :Menu Item: Menu Item Definition.
-
-
-Context Sensitive Manual Access
-===============================
-
-It is possible to link to a specific part of the manual from in Blender by
-right clicking on 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 right click on
-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
- =========
-
-
Code Samples
============
@@ -312,51 +232,36 @@
`Blender Website <https://www.blender.org>`__
-Directory Layout
-================
+Context Sensitive Manual Access
+-------------------------------
-Sections should be generally structured as follows:
+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::
-- ``directory_name/``
+ .. _bpy.types.FluidDomainSettings.use_fractions:
- - ``index.rst`` (contains links to internal files)
- - ``introduction.rst``
- - ``section_1.rst``
- - ``section_2.rst``
+ Fractional Obstacles
+ Enables finer resolution in fluid / obstacle regions (second order obstacles)...
-For example:
+ .. _bpy.types.FluidDomainSettings.fractions_distance:
-- ``rendering/``
+ Obstacle Distance
+ Determines how far apart fluid and obstacles are...
- - ``index.rst``
- - ``cycles/``
+For an operator::
- - ``index.rst``
- - ``introduction.rst``
- - ``materials/``
+ .. _bpy.ops.curve.subdivide:
- - ``index.rst``
- - ``introduction.rst``
- - ``volumes.rst``
+ Subdivide
+ =========
-The idea is to enclose all the content of a section inside of a folder. Ideally every section
-should have an ``index.rst`` (containing the TOC for that section) and an ``introduction.rst``
-(introducing) to the contents of the section.
-
-Table of Contents
------------------
-
-By default, a table of contents should show two levels of depth::
-
- .. toctree::
- :maxdepth: 2
-
- introduction.rst
- perspective.rst
- depth_of_field.rst
-
-
Further Reading
===============
Added: branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/templates.rst
===================================================================
--- branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/templates.rst (rev 0)
+++ branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/templates.rst 2021-05-19 23:58:20 UTC (rev 8049)
@@ -0,0 +1,143 @@
+.. highlight:: rst
+
+*********
+Templates
+*********
+
+The following guide provides patterns for interface elements and directories.
+
+
+Operator Menus
+==============
+
+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::
+
+ .. admonition:: Reference
+ :class: refbox
+
+ :Mode: Edit Mode
+ :Menu: :menuselection:`Curve --> Snap`
+ :Shortcut: :kbd:`Shift-S`
+
+
+Panels
+======
+
+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::
+
+ Panel Title
+ ===========
+
+ Nested Panel Title
+ ------------------
+
+
+Properties
+==========
+
+Properties should be documented using definition lists.
+Properties that are hidden based on other properties should used nested definitions::
+
+ Property
+ Property description.
+
+ Hidden Property
+ Hidden property description.
+
+Select menus should be documented using the following syntax::
+
+ Menu Label
+ General description of the menu.
+
+ :Menu Item: Menu Item Definition.
+ :Menu Item: Menu Item Definition.
+ :Menu Item: Menu Item Definition.
+
+
+Nodes
+=====
+
+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::
+
+ **********
+ World Node
+ **********
+
+ .. figure:: /images/render_shader-nodes_output_world_node.png
+ :align: right
+
+ The World node.
+
+ Introduction and general use case(s).
+
+
+ Inputs
+ ======
+
+ This node has no inputs.
+
+
+ Properties
+ ==========
+
+ This node has no properties.
+
+
+ Outputs
+ =======
+
+ This node has no outputs.
+
+
+ Example
+ =======
+
+
+Directory Layout
+================
+
+Sections should be generally structured as follows:
+
+- ``directory_name/``
+
+ - ``index.rst`` (contains links to internal files)
+ - ``introduction.rst``
+ - ``section_1.rst``
+ - ``section_2.rst``
+
+For example:
+
+- ``rendering/``
+
+ - ``index.rst``
+ - ``cycles/``
+
+ - ``index.rst``
+ - ``introduction.rst``
+ - ``materials/``
+
+ - ``index.rst``
+ - ``introduction.rst``
+ - ``volumes.rst``
+
+The idea is to enclose all the content of a section inside of a folder. Ideally every section
+should have an ``index.rst`` (containing the TOC for that section) and an ``introduction.rst``
+(introducing) to the contents of the section.
+
+
+Table of Contents
+-----------------
+
+By default, a table of contents should show two levels of depth::
+
+ .. toctree::
+ :maxdepth: 2
+
+ introduction.rst
+ perspective.rst
+ depth_of_field.rst
Property changes on: branches/blender-2.93-release/blender_docs/manual/about/contribute/guides/templates.rst
___________________________________________________________________
Added: svn:eol-style
## -0,0 +1 ##
+native
\ No newline at end of property
Modified: branches/blender-2.93-release/blender_docs/manual/about/contribute/index.rst
===================================================================
--- branches/blender-2.93-release/blender_docs/manual/about/contribute/index.rst 2021-05-19 23:32:03 UTC (rev 8048)
+++ branches/blender-2.93-release/blender_docs/manual/about/contribute/index.rst 2021-05-19 23:58:20 UTC (rev 8049)
@@ -38,6 +38,7 @@
guides/writing_guide.rst
guides/markup_guide.rst
+ guides/templates.rst
guides/maintenance_guide.rst
Modified: branches/blender-2.93-release/blender_docs/manual/about/index.rst
===================================================================
--- branches/blender-2.93-release/blender_docs/manual/about/index.rst 2021-05-19 23:32:03 UTC (rev 8048)
+++ branches/blender-2.93-release/blender_docs/manual/about/index.rst 2021-05-19 23:58:20 UTC (rev 8049)
@@ -40,6 +40,7 @@
contribute/guides/writing_guide.rst
contribute/guides/markup_guide.rst
+ contribute/guides/templates.rst
contribute/guides/maintenance_guide.rst
More information about the Bf-docboard-svn
mailing list