Pydoc: Fix sphinx compile warnings about freestyle

Sphinx expects functions and methods with the same name and different
parameters to be written using one directive. See:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#basic-markup

Unfortunately this makes giving different descriptions for each harder.
This was already a request for better support for this in sphinx, see:
https://github.com/sphinx-doc/sphinx/issues/7787

Reviewed By: campbellbarton

Differential Revision: https://developer.blender.org/D9170

1 files changed, 58 insertions, 125 deletions

diff --git a/source/blender/freestyle/intern/python/BPy_Operators.cpp b/source/blender/freestyle/intern/python/BPy_Operators.cpp
index 56f95b8ecbb..1235786d5d3 100644
--- a/source/blender/freestyle/intern/python/BPy_Operators.cpp
+++ b/source/blender/freestyle/intern/python/BPy_Operators.cpp
@@ -101,6 +101,7 @@ static PyObject *Operators_select(BPy_Operators * /*self*/, PyObject *args, PyOb
 
 PyDoc_STRVAR(Operators_chain_doc,
              ".. staticmethod:: chain(it, pred, modifier)\n"
+             "                  chain(it, pred)\n"
              "\n"
              "   Builds a set of chains from the current set of ViewEdges.  Each\n"
              "   ViewEdge of the current list starts a new chain.  The chaining\n"
@@ -116,28 +117,9 @@ PyDoc_STRVAR(Operators_chain_doc,
              "   :type pred: :class:`UnaryPredicate1D`\n"
              "   :arg modifier: A function that takes a ViewEdge as argument and\n"
              "      that is used to modify the processed ViewEdge state (the\n"
-             "      timestamp incrementation is a typical illustration of such a\n"
-             "      modifier).\n"
-             "   :type modifier: :class:`UnaryFunction1DVoid`\n"
-             "\n"
-             ".. staticmethod:: chain(it, pred)\n"
-             "\n"
-             "   Builds a set of chains from the current set of ViewEdges.  Each\n"
-             "   ViewEdge of the current list starts a new chain.  The chaining\n"
-             "   operator then iterates over the ViewEdges of the ViewMap using the\n"
-             "   user specified iterator.  This operator only iterates using the\n"
-             "   increment operator and is therefore unidirectional.  This chaining\n"
-             "   operator is different from the previous one because it doesn't take\n"
-             "   any modifier as argument.  Indeed, the time stamp (insuring that a\n"
-             "   ViewEdge is processed one time) is automatically managed in this\n"
-             "   case.\n"
-             "\n"
-             "   :arg it: The iterator on the ViewEdges of the ViewMap. It contains\n"
-             "      the chaining rule. \n"
-             "   :type it: :class:`ViewEdgeIterator`\n"
-             "   :arg pred: The predicate on the ViewEdge that expresses the\n"
-             "      stopping condition.\n"
-             "   :type pred: :class:`UnaryPredicate1D`");
+             "      timestamp incrementation is a typical illustration of such a modifier).\n"
+             "      If this argument is not given, the time stamp is automatically managed.\n"
+             "   :type modifier: :class:`UnaryFunction1DVoid`\n");
 
 static PyObject *Operators_chain(BPy_Operators * /*self*/, PyObject *args, PyObject *kwds)
 {
@@ -195,6 +177,7 @@ static PyObject *Operators_chain(BPy_Operators * /*self*/, PyObject *args, PyObj
 
 PyDoc_STRVAR(Operators_bidirectional_chain_doc,
              ".. staticmethod:: bidirectional_chain(it, pred)\n"
+             "                  bidirectional_chain(it)\n"
              "\n"
              "   Builds a set of chains from the current set of ViewEdges.  Each\n"
              "   ViewEdge of the current list potentially starts a new chain.  The\n"
@@ -211,30 +194,10 @@ PyDoc_STRVAR(Operators_bidirectional_chain_doc,
              "   :arg it: The ChainingIterator on the ViewEdges of the ViewMap.  It\n"
              "      contains the chaining rule.\n"
              "   :type it: :class:`ChainingIterator`\n"
-             "   :arg pred: The predicate on the ViewEdge that expresses the\n"
-             "      stopping condition.\n"
-             "   :type pred: :class:`UnaryPredicate1D`\n"
-             "\n"
-             ".. staticmethod:: bidirectional_chain(it)\n"
-             "\n"
-             "   The only difference with the above bidirectional chaining algorithm\n"
-             "   is that we don't need to pass a stopping criterion.  This might be\n"
-             "   desirable when the stopping criterion is already contained in the\n"
-             "   iterator definition.  Builds a set of chains from the current set of\n"
-             "   ViewEdges.  Each ViewEdge of the current list potentially starts a new\n"
-             "   chain.  The chaining operator then iterates over the ViewEdges of the\n"
-             "   ViewMap using the user specified iterator.  This operator iterates\n"
-             "   both using the increment and decrement operators and is therefore\n"
-             "   bidirectional.  This operator works with a ChainingIterator which\n"
-             "   contains the chaining rules.  It is this last one which can be told to\n"
-             "   chain only edges that belong to the selection or not to process twice\n"
-             "   a ViewEdge during the chaining.  Each time a ViewEdge is added to a\n"
-             "   chain, its chaining time stamp is incremented.  This allows you to\n"
-             "   keep track of the number of chains to which a ViewEdge belongs to.\n"
-             "\n"
-             "   :arg it: The ChainingIterator on the ViewEdges of the ViewMap.  It\n"
-             "      contains the chaining rule.\n"
-             "   :type it: :class:`ChainingIterator`");
+             "   :arg pred: The predicate on the ViewEdge that expresses the stopping condition.\n"
+             "      This parameter is optional, you make not want to pass a stopping criterion\n"
+             "      when the stopping criterion is already contained in the iterator definition.\n"
+             "   :type pred: :class:`UnaryPredicate1D`\n");
 
 static PyObject *Operators_bidirectional_chain(BPy_Operators * /*self*/,
                                                PyObject *args,
@@ -287,44 +250,34 @@ static PyObject *Operators_bidirectional_chain(BPy_Operators * /*self*/,
 
 PyDoc_STRVAR(Operators_sequential_split_doc,
              ".. staticmethod:: sequential_split(starting_pred, stopping_pred, sampling=0.0)\n"
+             "                  sequential_split(pred, sampling=0.0)\n"
              "\n"
              "   Splits each chain of the current set of chains in a sequential way.\n"
              "   The points of each chain are processed (with a specified sampling)\n"
-             "   sequentially. Each time a user specified starting condition is\n"
-             "   verified, a new chain begins and ends as soon as a user-defined\n"
-             "   stopping predicate is verified. This allows chains overlapping rather\n"
-             "   than chains partitioning. The first point of the initial chain is the\n"
+             "   sequentially. The first point of the initial chain is the\n"
              "   first point of one of the resulting chains. The splitting ends when\n"
              "   no more chain can start.\n"
              "\n"
+             "   .. tip::\n"
+             "\n"
+             "      By specifiying a starting and stopping predicate allows\n"
+             "      the chains to overlapp rather than chains partitioning.\n"
+             "\n"
              "   :arg starting_pred: The predicate on a point that expresses the\n"
-             "      starting condition.\n"
+             "      starting condition. Each time this condition is verified, a new chain begins\n"
              "   :type starting_pred: :class:`UnaryPredicate0D`\n"
              "   :arg stopping_pred: The predicate on a point that expresses the\n"
-             "      stopping condition.\n"
+             "      stopping condition. The chain ends as soon as this predicate is verified.\n"
              "   :type stopping_pred: :class:`UnaryPredicate0D`\n"
+             "   :arg pred: The predicate on a point that expresses the splitting condition.\n"
+             "      Each time the condition is verified, the chain is split into two chains.\n"
+             "      The resulting set of chains is a partition of the initial chain\n"
+             "   :type pred: :class:`UnaryPredicate0D`\n"
              "   :arg sampling: The resolution used to sample the chain for the\n"
              "      predicates evaluation. (The chain is not actually resampled;\n"
              "      a virtual point only progresses along the curve using this\n"
              "      resolution.)\n"
-             "   :type sampling: float\n"
-             "\n"
-             ".. staticmethod:: sequential_split(pred, sampling=0.0)\n"
-             "\n"
-             "   Splits each chain of the current set of chains in a sequential way.\n"
-             "   The points of each chain are processed (with a specified sampling)\n"
-             "   sequentially and each time a user specified condition is verified,\n"
-             "   the chain is split into two chains.  The resulting set of chains is a\n"
-             "   partition of the initial chain\n"
-             "\n"
-             "   :arg pred: The predicate on a point that expresses the splitting\n"
-             "      condition.\n"
-             "   :type pred: :class:`UnaryPredicate0D`\n"
-             "   :arg sampling: The resolution used to sample the chain for the\n"
-             "      predicate evaluation. (The chain is not actually resampled; a\n"
-             "      virtual point only progresses along the curve using this\n"
-             "      resolution.)\n"
-             "   :type sampling: float");
+             "   :type sampling: float\n");
 
 static PyObject *Operators_sequential_split(BPy_Operators * /*self*/,
                                             PyObject *args,
@@ -389,61 +342,41 @@ static PyObject *Operators_sequential_split(BPy_Operators * /*self*/,
   Py_RETURN_NONE;
 }
 
-PyDoc_STRVAR(Operators_recursive_split_doc,
-             ".. staticmethod:: recursive_split(func, pred_1d, sampling=0.0)\n"
-             "\n"
-             "   Splits the current set of chains in a recursive way.  We process the\n"
-             "   points of each chain (with a specified sampling) to find the point\n"
-             "   minimizing a specified function.  The chain is split in two at this\n"
-             "   point and the two new chains are processed in the same way.  The\n"
-             "   recursivity level is controlled through a predicate 1D that expresses\n"
-             "   a stopping condition on the chain that is about to be processed.\n"
-             "\n"
-             "   :arg func: The Unary Function evaluated at each point of the chain.\n"
-             "     The splitting point is the point minimizing this function.\n"
-             "   :type func: :class:`UnaryFunction0DDouble`\n"
-             "   :arg pred_1d: The Unary Predicate expressing the recursivity stopping\n"
-             "      condition.  This predicate is evaluated for each curve before it\n"
-             "      actually gets split.  If pred_1d(chain) is true, the curve won't be\n"
-             "      split anymore.\n"
-             "   :type pred_1d: :class:`UnaryPredicate1D`\n"
-             "   :arg sampling: The resolution used to sample the chain for the\n"
-             "      predicates evaluation. (The chain is not actually resampled, a\n"
-             "      virtual point only progresses along the curve using this\n"
-             "      resolution.)\n"
-             "   :type sampling: float\n"
-             "\n"
-             ".. staticmethod:: recursive_split(func, pred_0d, pred_1d, sampling=0.0)\n"
-             "\n"
-             "   Splits the current set of chains in a recursive way.  We process the\n"
-             "   points of each chain (with a specified sampling) to find the point\n"
-             "   minimizing a specified function.  The chain is split in two at this\n"
-             "   point and the two new chains are processed in the same way.  The user\n"
-             "   can specify a 0D predicate to make a first selection on the points\n"
-             "   that can potentially be split.  A point that doesn't verify the 0D\n"
-             "   predicate won't be candidate in realizing the min.  The recursivity\n"
-             "   level is controlled through a predicate 1D that expresses a stopping\n"
-             "   condition on the chain that is about to be processed.\n"
-             "\n"
-             "   :arg func: The Unary Function evaluated at each point of the chain.\n"
-             "      The splitting point is the point minimizing this function.\n"
-             "   :type func: :class:`UnaryFunction0DDouble`\n"
-             "   :arg pred_0d: The Unary Predicate 0D used to select the candidate\n"
-             "      points where the split can occur.  For example, it is very likely\n"
-             "      that would rather have your chain splitting around its middle\n"
-             "      point than around one of its extremities.  A 0D predicate working\n"
-             "      on the curvilinear abscissa allows to add this kind of constraints.\n"
-             "   :type pred_0d: :class:`UnaryPredicate0D`\n"
-             "   :arg pred_1d: The Unary Predicate expressing the recursivity stopping\n"
-             "      condition. This predicate is evaluated for each curve before it\n"
-             "      actually gets split.  If pred_1d(chain) is true, the curve won't be\n"
-             "      split anymore.\n"
-             "   :type pred_1d: :class:`UnaryPredicate1D`\n"
-             "   :arg sampling: The resolution used to sample the chain for the\n"
-             "      predicates evaluation. (The chain is not actually resampled; a\n"
-             "      virtual point only progresses along the curve using this\n"
-             "      resolution.)\n"
-             "   :type sampling: float");
+PyDoc_STRVAR(
+    Operators_recursive_split_doc,
+    ".. staticmethod:: recursive_split(func, pred_1d, sampling=0.0)\n"
+    "                  recursive_split(func, pred_0d, pred_1d, sampling=0.0)\n"
+    "\n"
+    "   Splits the current set of chains in a recursive way.  We process the\n"
+    "   points of each chain (with a specified sampling) to find the point\n"
+    "   minimizing a specified function. The chain is split in two at this\n"
+    "   point and the two new chains are processed in the same way. The\n"
+    "   recursivity level is controlled through a predicate 1D that expresses\n"
+    "   a stopping condition on the chain that is about to be processed.\n"
+    "\n"
+    "   The user can also specify a 0D predicate to make a first selection on the points\n"
+    "   that can potentially be split. A point that doesn't verify the 0D\n"
+    "   predicate won't be candidate in realizing the min.\n"
+    "\n"
+    "   :arg func: The Unary Function evaluated at each point of the chain.\n"
+    "     The splitting point is the point minimizing this function.\n"
+    "   :type func: :class:`UnaryFunction0DDouble`\n"
+    "   :arg pred_0d: The Unary Predicate 0D used to select the candidate\n"
+    "      points where the split can occur.  For example, it is very likely\n"
+    "      that would rather have your chain splitting around its middle\n"
+    "      point than around one of its extremities.  A 0D predicate working\n"
+    "      on the curvilinear abscissa allows to add this kind of constraints.\n"
+    "   :type pred_0d: :class:`UnaryPredicate0D`\n"
+    "   :arg pred_1d: The Unary Predicate expressing the recursivity stopping\n"
+    "      condition.  This predicate is evaluated for each curve before it\n"
+    "      actually gets split.  If pred_1d(chain) is true, the curve won't be\n"
+    "      split anymore.\n"
+    "   :type pred_1d: :class:`UnaryPredicate1D`\n"
+    "   :arg sampling: The resolution used to sample the chain for the\n"
+    "      predicates evaluation. (The chain is not actually resampled; a\n"
+    "      virtual point only progresses along the curve using this\n"
+    "      resolution.)\n"
+    "   :type sampling: float\n");
 
 static PyObject *Operators_recursive_split(BPy_Operators * /*self*/,
                                            PyObject *args,