Fix for missing Freestyle sections in the Blender Python API documentation.

Freestyle sections of the API docs were empty due to Freestyle module reorganization in commit rB6498b96ce7081db039354228213d72e8c70bd3aa. Module __all__ property was added to submodules so as to properly exclude irrelevant documentation elements such as mathutils.Vector.
Referenced by commit e1983adef4, PYAPI: Fix freestyle submodules without tocrees
2014-09-18 15:44:53 +09:00 · 2014-09-18 15:44:53 +09:00 · f87ca5f1c3 · 2023-02-14 07:25:51 +01:00
parent 3c28eecb6e
commit f87ca5f1c3
9 changed files with 394 additions and 21 deletions
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@ -274,6 +274,12 @@ else:
        "mathutils.kdtree",
        "mathutils.noise",
        "freestyle",
+        "freestyle.chainingiterators",
+        "freestyle.functions",
+        "freestyle.predicates",
+        "freestyle.shaders",
+        "freestyle.types",
+        "freestyle.utils",
        ]

    # ------
@ -316,7 +322,13 @@ try:
    __import__("freestyle")
 except ImportError:
    BPY_LOGGER.debug("Warning: Built without 'freestyle' module, docs incomplete...")
-    EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["freestyle"]
+    EXCLUDE_MODULES = list(EXCLUDE_MODULES) + ["freestyle",
+                                               "freestyle.chainingiterators",
+                                               "freestyle.functions",
+                                               "freestyle.predicates",
+                                               "freestyle.shaders",
+                                               "freestyle.types",
+                                               "freestyle.utils"]

 # examples
 EXAMPLES_DIR = os.path.abspath(os.path.join(SCRIPT_DIR, "examples"))
@ -1780,8 +1792,14 @@ def write_rst_importable_modules(basepath):
        "mathutils.geometry"   : "Geometry Utilities",
        "mathutils.kdtree"     : "KDTree Utilities",
        "mathutils.noise"      : "Noise Utilities",
-        "freestyle"            : "Freestyle Data Types & Operators",
-    }
+        "freestyle"            : "Freestyle Module",
+        "freestyle.types"      : "Freestyle Types",
+        "freestyle.predicates" : "Freestyle Predicates",
+        "freestyle.functions"  : "Freestyle Functions",
+        "freestyle.chainingiterators" : "Freestyle Chaining Iterators",
+        "freestyle.shaders"    : "Freestyle Shaders",
+        "freestyle.utils"      : "Freestyle Utilities",
+        }
    for mod_name, mod_descr in importable_modules.items():
        if mod_name not in EXCLUDE_MODULES:
            module = __import__(mod_name,
--- a/release/scripts/freestyle/modules/freestyle/init.py
+++ b/release/scripts/freestyle/modules/freestyle/init.py
@ -17,8 +17,21 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Top-level module containing all Freestyle stylization constructs
+This module provides data types of view map components (0D and 1D
+elements), base classes for defining line stylization rules
+(predicates, functions, chaining iterators, and stroke shaders), as
+well as helper functions for style module writing.
+
+Submodules:
+
+* :mod:`freestyle.types`
+* :mod:`freestyle.predicates`
+* :mod:`freestyle.functions`
+* :mod:`freestyle.chainingiterators`
+* :mod:`freestyle.shaders`
+* :mod:`freestyle.utils`
 """

+
 # module members
 from . import chainingiterators, functions, predicates, shaders, types, utils
--- a/release/scripts/freestyle/modules/freestyle/chainingiterators.py
+++ b/release/scripts/freestyle/modules/freestyle/chainingiterators.py
@ -17,10 +17,10 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Chaining iterators used for the chaining operation to construct long
-strokes by concatenating feature edges according to selected chaining
-rules.  Also intended to be a collection of examples for defining
-chaining iterators in Python
+This module contains chaining iterators used for the chaining
+operation to construct long strokes by concatenating feature edges
+according to selected chaining rules.  The module is also intended to
+be a collection of examples for defining chaining iterators in Python.
 """

 __all__ = (
--- a/release/scripts/freestyle/modules/freestyle/functions.py
+++ b/release/scripts/freestyle/modules/freestyle/functions.py
@ -17,11 +17,99 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Functions operating on vertices (0D elements) and polylines (1D
-elements).  Also intended to be a collection of examples for predicate
-definition in Python.
+This module contains functions operating on vertices (0D elements) and
+polylines (1D elements).  The module is also intended to be a
+collection of examples for function definition in Python.
+
+User-defined functions inherit one of the following base classes,
+depending on the object type (0D or 1D) to operate on and the return
+value type:
+
+- :class:`freestyle.types.UnaryFunction0DDouble`
+- :class:`freestyle.types.UnaryFunction0DEdgeNature`
+- :class:`freestyle.types.UnaryFunction0DFloat`
+- :class:`freestyle.types.UnaryFunction0DId`
+- :class:`freestyle.types.UnaryFunction0DMaterial`
+- :class:`freestyle.types.UnaryFunction0DUnsigned`
+- :class:`freestyle.types.UnaryFunction0DVec2f`
+- :class:`freestyle.types.UnaryFunction0DVec3f`
+- :class:`freestyle.types.UnaryFunction0DVectorViewShape`
+- :class:`freestyle.types.UnaryFunction0DViewShape`
+- :class:`freestyle.types.UnaryFunction1DDouble`
+- :class:`freestyle.types.UnaryFunction1DEdgeNature`
+- :class:`freestyle.types.UnaryFunction1DFloat`
+- :class:`freestyle.types.UnaryFunction1DUnsigned`
+- :class:`freestyle.types.UnaryFunction1DVec2f`
+- :class:`freestyle.types.UnaryFunction1DVec3f`
+- :class:`freestyle.types.UnaryFunction1DVectorViewShape`
+- :class:`freestyle.types.UnaryFunction1DVoid`
 """

+__all__ = (
+    "ChainingTimeStampF1D",
+    "Curvature2DAngleF0D",
+    "Curvature2DAngleF1D",
+    "CurveMaterialF0D",
+    "CurveNatureF0D",
+    "CurveNatureF1D",
+    "DensityF0D",
+    "DensityF1D",
+    "GetCompleteViewMapDensityF1D",
+    "GetCurvilinearAbscissaF0D",
+    "GetDirectionalViewMapDensityF1D",
+    "GetOccludeeF0D",
+    "GetOccludeeF1D",
+    "GetOccludersF0D",
+    "GetOccludersF1D",
+    "GetParameterF0D",
+    "GetProjectedXF0D",
+    "GetProjectedXF1D",
+    "GetProjectedYF0D",
+    "GetProjectedYF1D",
+    "GetProjectedZF0D",
+    "GetProjectedZF1D",
+    "GetShapeF0D",
+    "GetShapeF1D",
+    "GetSteerableViewMapDensityF1D",
+    "GetViewMapGradientNormF0D",
+    "GetViewMapGradientNormF1D",
+    "GetXF0D",
+    "GetXF1D",
+    "GetYF0D",
+    "GetYF1D",
+    "GetZF0D",
+    "GetZF1D",
+    "IncrementChainingTimeStampF1D",
+    "LocalAverageDepthF0D",
+    "LocalAverageDepthF1D",
+    "MaterialF0D",
+    "Normal2DF0D",
+    "Normal2DF1D",
+    "Orientation2DF1D",
+    "Orientation3DF1D",
+    "QuantitativeInvisibilityF0D",
+    "QuantitativeInvisibilityF1D",
+    "ReadCompleteViewMapPixelF0D",
+    "ReadMapPixelF0D",
+    "ReadSteerableViewMapPixelF0D",
+    "ShapeIdF0D",
+    "TimeStampF1D",
+    "VertexOrientation2DF0D",
+    "VertexOrientation3DF0D",
+    "ZDiscontinuityF0D",
+    "ZDiscontinuityF1D",
+    "pyCurvilinearLengthF0D",
+    "pyDensityAnisotropyF0D",
+    "pyDensityAnisotropyF1D",
+    "pyGetInverseProjectedZF1D",
+    "pyGetSquareInverseProjectedZF1D",
+    "pyInverseCurvature2DAngleF0D",
+    "pyViewMapGradientNormF0D",
+    "pyViewMapGradientNormF1D",
+    "pyViewMapGradientVectorF0D",
+    )
+
+
 # module members
 from _freestyle import (
    ChainingTimeStampF1D,
--- a/release/scripts/freestyle/modules/freestyle/predicates.py
+++ b/release/scripts/freestyle/modules/freestyle/predicates.py
@ -17,11 +17,84 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Predicates operating on vertices (0D elements) and polylines (1D
-elements).  Also intended to be a collection of examples for predicate
-definition in Python
+This module contains predicates operating on vertices (0D elements)
+and polylines (1D elements).  It is also intended to be a collection
+of examples for predicate definition in Python.
+
+User-defined predicates inherit one of the following base classes,
+depending on the object type (0D or 1D) to operate on and the arity
+(unary or binary):
+
+- :class:`freestyle.types.BinaryPredicate0D`
+- :class:`freestyle.types.BinaryPredicate1D`
+- :class:`freestyle.types.UnaryPredicate0D`
+- :class:`freestyle.types.UnaryPredicate1D`
 """

+__all__ = (
+    "AndBP1D",
+    "AndUP1D",
+    "ContourUP1D",
+    "DensityLowerThanUP1D",
+    "EqualToChainingTimeStampUP1D",
+    "EqualToTimeStampUP1D",
+    "ExternalContourUP1D",
+    "FalseBP1D",
+    "FalseUP0D",
+    "FalseUP1D",
+    "Length2DBP1D",
+    "NotBP1D",
+    "NotUP1D",
+    "ObjectNamesUP1D",
+    "OrBP1D",
+    "OrUP1D",
+    "QuantitativeInvisibilityRangeUP1D",
+    "QuantitativeInvisibilityUP1D",
+    "SameShapeIdBP1D",
+    "ShapeUP1D",
+    "TrueBP1D",
+    "TrueUP0D",
+    "TrueUP1D",
+    "ViewMapGradientNormBP1D",
+    "WithinImageBoundaryUP1D",
+    "pyBackTVertexUP0D",
+    "pyClosedCurveUP1D",
+    "pyDensityFunctorUP1D",
+    "pyDensityUP1D",
+    "pyDensityVariableSigmaUP1D",
+    "pyHighDensityAnisotropyUP1D",
+    "pyHighDirectionalViewMapDensityUP1D",
+    "pyHighSteerableViewMapDensityUP1D",
+    "pyHighViewMapDensityUP1D",
+    "pyHighViewMapGradientNormUP1D",
+    "pyHigherCurvature2DAngleUP0D",
+    "pyHigherLengthUP1D",
+    "pyHigherNumberOfTurnsUP1D",
+    "pyIsInOccludersListUP1D",
+    "pyIsOccludedByIdListUP1D",
+    "pyIsOccludedByItselfUP1D",
+    "pyIsOccludedByUP1D",
+    "pyLengthBP1D",
+    "pyLowDirectionalViewMapDensityUP1D",
+    "pyLowSteerableViewMapDensityUP1D",
+    "pyNFirstUP1D",
+    "pyNatureBP1D",
+    "pyNatureUP1D",
+    "pyParameterUP0D",
+    "pyParameterUP0DGoodOne",
+    "pyShapeIdListUP1D",
+    "pyShapeIdUP1D",
+    "pyShuffleBP1D",
+    "pySilhouetteFirstBP1D",
+    "pyUEqualsUP0D",
+    "pyVertexNatureUP0D",
+    "pyViewMapGradientNormBP1D",
+    "pyZBP1D",
+    "pyZDiscontinuityBP1D",
+    "pyZSmallerUP1D",
+    )
+
+
 # module members
 from _freestyle import (
    ContourUP1D,
--- a/release/scripts/freestyle/modules/freestyle/shaders.py
+++ b/release/scripts/freestyle/modules/freestyle/shaders.py
@ -22,10 +22,80 @@
 #  Purpose  : Stroke shaders to be used for creation of stylized strokes

 """
-Stroke shaders used for creation of stylized strokes.  Also intended
-to be a collection of examples for shader definition in Python.
+This module contains stroke shaders used for creation of stylized
+strokes.  It is also intended to be a collection of examples for
+shader definition in Python.
+
+User-defined stroke shaders inherit the
+:class:`freestyle.types.StrokeShader` class.
 """

+__all__ = (
+    "BackboneStretcherShader",
+    "BezierCurveShader",
+    "BlenderTextureShader",
+    "CalligraphicShader",
+    "ColorNoiseShader",
+    "ColorVariationPatternShader",
+    "ConstantColorShader",
+    "ConstantThicknessShader",
+    "ConstrainedIncreasingThicknessShader",
+    "GuidingLinesShader",
+    "IncreasingColorShader",
+    "IncreasingThicknessShader",
+    "PolygonalizationShader",
+    "RoundCapShader",
+    "SamplingShader",
+    "SmoothingShader",
+    "SpatialNoiseShader",
+    "SquareCapShader",
+    "StrokeTextureShader",
+    "StrokeTextureStepShader",
+    "TextureAssignerShader",
+    "ThicknessNoiseShader",
+    "ThicknessVariationPatternShader",
+    "TipRemoverShader",
+    "fstreamShader",
+    "py2DCurvatureColorShader",
+    "pyBackboneStretcherNoCuspShader",
+    "pyBackboneStretcherShader",
+    "pyBluePrintCirclesShader",
+    "pyBluePrintDirectedSquaresShader",
+    "pyBluePrintEllipsesShader",
+    "pyBluePrintSquaresShader",
+    "pyConstantColorShader",
+    "pyConstantThicknessShader",
+    "pyConstrainedIncreasingThicknessShader",
+    "pyDecreasingThicknessShader",
+    "pyDepthDiscontinuityThicknessShader",
+    "pyDiffusion2Shader",
+    "pyFXSVaryingThicknessWithDensityShader",
+    "pyGuidingLineShader",
+    "pyHLRShader",
+    "pyImportance2DThicknessShader",
+    "pyImportance3DThicknessShader",
+    "pyIncreasingColorShader",
+    "pyIncreasingThicknessShader",
+    "pyInterpolateColorShader",
+    "pyLengthDependingBackboneStretcherShader",
+    "pyMaterialColorShader",
+    "pyModulateAlphaShader",
+    "pyNonLinearVaryingThicknessShader",
+    "pyPerlinNoise1DShader",
+    "pyPerlinNoise2DShader",
+    "pyRandomColorShader",
+    "pySLERPThicknessShader",
+    "pySamplingShader",
+    "pySinusDisplacementShader",
+    "pyTVertexRemoverShader",
+    "pyTVertexThickenerShader",
+    "pyTimeColorShader",
+    "pyTipRemoverShader",
+    "pyZDependingThicknessShader",
+    "streamShader",
+    )
+
+
 # module members
 from _freestyle import (
    BackboneStretcherShader,
--- a/release/scripts/freestyle/modules/freestyle/types.py
+++ b/release/scripts/freestyle/modules/freestyle/types.py
@ -17,9 +17,96 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Submodule containing all Freestyle types.
+This module contains core classes of the Freestyle Python API,
+including data types of view map components (0D and 1D elements), base
+classes for user-defined line stylization rules (predicates,
+functions, chaining iterators, and stroke shaders), and operators.
+
+Class hierarchy:
+
+- :class:`BBox`
+- :class:`BinaryPredicate0D`
+- :class:`BinaryPredicate1D`
+- :class:`Id`
+- :class:`Interface0D`
+
+  - :class:`CurvePoint`
+
+    - :class:`StrokeVertex`
+
+  - :class:`SVertex`
+  - :class:`ViewVertex`
+
+    - :class:`NonTVertex`
+    - :class:`TVertex`
+
+- :class:`Interface1D`
+
+  - :class:`Curve`
+
+    - :class:`Chain`
+
+  - :class:`FEdge`
+
+    - :class:`FEdgeSharp`
+    - :class:`FEdgeSmooth`
+
+  - :class:`Stroke`
+  - :class:`ViewEdge`
+
+- :class:`Iterator`
+
+  - :class:`AdjacencyIterator`
+  - :class:`CurvePointIterator`
+  - :class:`Interface0DIterator`
+  - :class:`SVertexIterator`
+  - :class:`StrokeVertexIterator`
+  - :class:`ViewEdgeIterator`
+
+    - :class:`ChainingIterator`
+
+  - :class:`orientedViewEdgeIterator`
+
+- :class:`Material`
+- :class:`Noise`
+- :class:`Operators`
+- :class:`SShape`
+- :class:`StrokeAttribute`
+- :class:`StrokeShader`
+- :class:`UnaryFunction0D`
+
+  - :class:`UnaryFunction0DDouble`
+  - :class:`UnaryFunction0DEdgeNature`
+  - :class:`UnaryFunction0DFloat`
+  - :class:`UnaryFunction0DId`
+  - :class:`UnaryFunction0DMaterial`
+  - :class:`UnaryFunction0DUnsigned`
+  - :class:`UnaryFunction0DVec2f`
+  - :class:`UnaryFunction0DVec3f`
+  - :class:`UnaryFunction0DVectorViewShape`
+  - :class:`UnaryFunction0DViewShape`
+
+- :class:`UnaryFunction1D`
+
+  - :class:`UnaryFunction1DDouble`
+  - :class:`UnaryFunction1DEdgeNature`
+  - :class:`UnaryFunction1DFloat`
+  - :class:`UnaryFunction1DUnsigned`
+  - :class:`UnaryFunction1DVec2f`
+  - :class:`UnaryFunction1DVec3f`
+  - :class:`UnaryFunction1DVectorViewShape`
+  - :class:`UnaryFunction1DVoid`
+
+- :class:`UnaryPredicate0D`
+- :class:`UnaryPredicate1D`
+- :class:`ViewMap`
+- :class:`ViewShape`
+- :class:`IntegrationType`
+- :class:`MediumType`
+- :class:`Nature`
 """

+
 # module members
 from _freestyle import (
    AdjacencyIterator,
--- a/release/scripts/freestyle/modules/freestyle/utils.py
+++ b/release/scripts/freestyle/modules/freestyle/utils.py
@ -17,9 +17,33 @@
 # ##### END GPL LICENSE BLOCK #####

 """
-Helper functions used for Freestyle style module writing.
+This module contains helper functions used for Freestyle style module
+writing.
 """

+__all__ = (
+    "ContextFunctions",
+    "bound",
+    "bounding_box",
+    "find_matching_vertex",
+    "getCurrentScene",
+    "get_chain_length",
+    "get_test_stroke",
+    "integrate",
+    "iter_distance_along_stroke",
+    "iter_distance_from_camera",
+    "iter_distance_from_object",
+    "iter_material_value",
+    "iter_t2d_along_stroke",
+    "pairwise",
+    "phase_to_direction",
+    "rgb_to_bw",
+    "stroke_curvature",
+    "stroke_normal",
+    "tripplewise",
+    )
+
+
 # module members
 from _freestyle import (
    ContextFunctions,
@ -27,13 +51,13 @@ from _freestyle import (
    integrate,
    )

+# constructs for helper functions in Python
 from freestyle.types import (
    Interface0DIterator,
    Stroke,
    StrokeVertexIterator,
    )

-
 from mathutils import Vector
 from functools import lru_cache, namedtuple
 from math import cos, sin, pi
--- a/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp
@ -138,8 +138,8 @@ static PyObject *Interface0DIterator_iternext(BPy_Interface0DIterator *self)
 PyDoc_STRVAR(Interface0DIterator_object_doc,
 "The 0D object currently pointed to by this iterator.  Note that the object\n"
 "may be an instance of an Interface0D subclass. For example if the iterator\n"
-"has been created from :method:`Stroke.vertices_begin`, the .object property\n"
-"refers to a :class:`StrokeVertex` object.\n"
+"has been created from the `vertices_begin()` method of the :class:`Stroke`\n"
+"class, the .object property refers to a :class:`StrokeVertex` object.\n"
 "\n"
 ":type: :class:`Interface0D` or one of its subclasses.");