Fix for missing Freestyle sections in the Blender Python API documentation.
authorTamito Kajiyama <rd6t-kjym@asahi-net.or.jp>
Thu, 18 Sep 2014 06:44:53 +0000 (15:44 +0900)
committerTamito Kajiyama <rd6t-kjym@asahi-net.or.jp>
Thu, 18 Sep 2014 06:48:15 +0000 (15:48 +0900)
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.

doc/python_api/sphinx_doc_gen.py
release/scripts/freestyle/modules/freestyle/__init__.py
release/scripts/freestyle/modules/freestyle/chainingiterators.py
release/scripts/freestyle/modules/freestyle/functions.py
release/scripts/freestyle/modules/freestyle/predicates.py
release/scripts/freestyle/modules/freestyle/shaders.py
release/scripts/freestyle/modules/freestyle/types.py
release/scripts/freestyle/modules/freestyle/utils.py
source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp

index 9ec8f9ad2c20c4c05bf362b6ab161769acbdcea7..226b1ecd1f3063cfaea11c2951102d5583541959 100644 (file)
@@ -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,
index 5874488f684b7857eb60712de340e6675266b92d..d2795f65b6affc789a70967ca07823409e90b3d3 100644 (file)
 # ##### 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
index 8d144bf17fd4a32a6d8151ec594332b69a64c17c..90523f94e6155f11b22ad885408f2eaaffe49654 100644 (file)
 # ##### 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__ = (
index 674c1f018643f449109d47240ae4aafb6893d255..8ad7e74ea8682a1f05751885738d3faddb61c88a 100644 (file)
 # ##### 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,
index 344b89d869cc260da8bf31445b5e7bafe028f28b..68ec9e05f6e646ce1bd5d2e7081e504b0f3089ec 100644 (file)
 # ##### 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,
index 502d9b69a97c671daf9ae6535447194916bad51e..108f5684bbae835e9d255674c32e7de72748f371 100644 (file)
 #  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,
index 8f596fd275c9e9906a98878e70c7a4e878bbda0e..22f80f41dfc8c5a8ce8ca078cf182ef9cbe13192 100644 (file)
 # ##### 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,
index e6dca93b7777f56288beeb6be5bc105f50a7ab57..e0679a539541382b8353cbbd8919cde8dd6f02cd 100644 (file)
 # ##### 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
index fca4c979bbbcf71b913b3fd093646c8e1e432e58..c972db1e68097564f55ff5a228f896558753259a 100644 (file)
@@ -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.");