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

10 files changed, 98 insertions, 139 deletions

diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
index 90e751333b9..dc32b73fda1 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_AdjacencyIterator.cpp
@@ -41,20 +41,14 @@ PyDoc_STRVAR(
     "traverse() method of the ChainingIterator.\n"
     "\n"
     ".. method:: __init__()\n"
+    "            __init__(brother)\n"
+    "            __init__(vertex, restrict_to_selection=True, restrict_to_unvisited=True)\n"
     "\n"
-    "   Default constructor.\n"
-    "\n"
-    ".. method:: __init__(brother)\n"
-    "\n"
-    "   Copy constructor.\n"
+    "   Builds an :class:`AdjacencyIterator` using the default constructor,\n"
+    "   copy constructor or the overloaded constructor.\n"
     "\n"
     "   :arg brother: An AdjacencyIterator object.\n"
     "   :type brother: :class:`AdjacencyIterator`\n"
-    "\n"
-    ".. method:: __init__(vertex, restrict_to_selection=True, restrict_to_unvisited=True)\n"
-    "\n"
-    "   Builds a AdjacencyIterator object.\n"
-    "\n"
     "   :arg vertex: The vertex which is the next crossing.\n"
     "   :type vertex: :class:`ViewVertex`\n"
     "   :arg restrict_to_selection: Indicates whether to force the chaining\n"
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_ChainPredicateIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_ChainPredicateIterator.cpp
index 1703fc2bddb..9c534a3463c 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_ChainPredicateIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_ChainPredicateIterator.cpp
@@ -33,55 +33,52 @@ extern "C" {
 
 //------------------------INSTANCE METHODS ----------------------------------
 
-PyDoc_STRVAR(ChainPredicateIterator_doc,
-
-             "Class hierarchy: :class:`freestyle.types.Iterator` >\n"
-             ":class:`freestyle.types.ViewEdgeIterator` >\n"
-             ":class:`freestyle.types.ChainingIterator` >\n"
-             ":class:`ChainPredicateIterator`\n"
-             "\n"
-             "A \"generic\" user-controlled ViewEdge iterator.  This iterator is in\n"
-             "particular built from a unary predicate and a binary predicate.\n"
-             "First, the unary predicate is evaluated for all potential next\n"
-             "ViewEdges in order to only keep the ones respecting a certain\n"
-             "constraint.  Then, the binary predicate is evaluated on the current\n"
-             "ViewEdge together with each ViewEdge of the previous selection.  The\n"
-             "first ViewEdge respecting both the unary predicate and the binary\n"
-             "predicate is kept as the next one.  If none of the potential next\n"
-             "ViewEdge respects these two predicates, None is returned.\n"
-             "\n"
-             ".. method:: __init__(upred, bpred, restrict_to_selection=True, "
-             "restrict_to_unvisited=True, begin=None, "
-             "orientation=True)\n"
-             "\n"
-             "   Builds a ChainPredicateIterator from a unary predicate, a binary\n"
-             "   predicate, a starting ViewEdge and its orientation.\n"
-             "\n"
-             "   :arg upred: The unary predicate that the next ViewEdge must satisfy.\n"
-             "   :type upred: :class:`freestyle.types.UnaryPredicate1D`\n"
-             "   :arg bpred: The binary predicate that the next ViewEdge must\n"
-             "      satisfy together with the actual pointed ViewEdge.\n"
-             "   :type bpred: :class:`freestyle.types.BinaryPredicate1D`\n"
-             "   :arg restrict_to_selection: Indicates whether to force the chaining\n"
-             "      to stay within the set of selected ViewEdges or not.\n"
-             "   :type restrict_to_selection: bool\n"
-             "   :arg restrict_to_unvisited: Indicates whether a ViewEdge that has\n"
-             "      already been chained must be ignored ot not.\n"
-             "   :type restrict_to_unvisited: bool\n"
-             "   :arg begin: The ViewEdge from where to start the iteration.\n"
-             "   :type begin: :class:`freestyle.types.ViewEdge` or None\n"
-             "   :arg orientation: If true, we'll look for the next ViewEdge among\n"
-             "      the ViewEdges that surround the ending ViewVertex of begin.  If\n"
-             "      false, we'll search over the ViewEdges surrounding the ending\n"
-             "      ViewVertex of begin.\n"
-             "   :type orientation: bool\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
-             "\n"
-             "   :arg brother: A ChainPredicateIterator object.\n"
-             "   :type brother: :class:`ChainPredicateIterator`");
+PyDoc_STRVAR(
+    ChainPredicateIterator_doc,
+
+    "Class hierarchy: :class:`freestyle.types.Iterator` >\n"
+    ":class:`freestyle.types.ViewEdgeIterator` >\n"
+    ":class:`freestyle.types.ChainingIterator` >\n"
+    ":class:`ChainPredicateIterator`\n"
+    "\n"
+    "A \"generic\" user-controlled ViewEdge iterator.  This iterator is in\n"
+    "particular built from a unary predicate and a binary predicate.\n"
+    "First, the unary predicate is evaluated for all potential next\n"
+    "ViewEdges in order to only keep the ones respecting a certain\n"
+    "constraint.  Then, the binary predicate is evaluated on the current\n"
+    "ViewEdge together with each ViewEdge of the previous selection.  The\n"
+    "first ViewEdge respecting both the unary predicate and the binary\n"
+    "predicate is kept as the next one.  If none of the potential next\n"
+    "ViewEdge respects these two predicates, None is returned.\n"
+    "\n"
+    ".. method:: __init__(upred, bpred, restrict_to_selection=True, "
+    "                     restrict_to_unvisited=True, begin=None, "
+    "                     orientation=True)\n"
+    "            __init__(brother)\n"
+    "\n"
+    "   Builds a ChainPredicateIterator from a unary predicate, a binary\n"
+    "   predicate, a starting ViewEdge and its orientation or using the copy constructor.\n"
+    "\n"
+    "   :arg upred: The unary predicate that the next ViewEdge must satisfy.\n"
+    "   :type upred: :class:`freestyle.types.UnaryPredicate1D`\n"
+    "   :arg bpred: The binary predicate that the next ViewEdge must\n"
+    "      satisfy together with the actual pointed ViewEdge.\n"
+    "   :type bpred: :class:`freestyle.types.BinaryPredicate1D`\n"
+    "   :arg restrict_to_selection: Indicates whether to force the chaining\n"
+    "      to stay within the set of selected ViewEdges or not.\n"
+    "   :type restrict_to_selection: bool\n"
+    "   :arg restrict_to_unvisited: Indicates whether a ViewEdge that has\n"
+    "      already been chained must be ignored ot not.\n"
+    "   :type restrict_to_unvisited: bool\n"
+    "   :arg begin: The ViewEdge from where to start the iteration.\n"
+    "   :type begin: :class:`freestyle.types.ViewEdge` or None\n"
+    "   :arg orientation: If true, we'll look for the next ViewEdge among\n"
+    "      the ViewEdges that surround the ending ViewVertex of begin.  If\n"
+    "      false, we'll search over the ViewEdges surrounding the ending\n"
+    "      ViewVertex of begin.\n"
+    "   :type orientation: bool\n"
+    "   :arg brother: A ChainPredicateIterator object.\n"
+    "   :type brother: :class:`ChainPredicateIterator`");
 
 static int check_begin(PyObject *obj, void *v)
 {
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_ChainSilhouetteIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_ChainSilhouetteIterator.cpp
index d8ad82d667c..9fa84d5f6b8 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_ChainSilhouetteIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_ChainSilhouetteIterator.cpp
@@ -48,9 +48,10 @@ PyDoc_STRVAR(ChainSilhouetteIterator_doc,
              "precedence of the silhouette over the crease criterion.\n"
              "\n"
              ".. method:: __init__(restrict_to_selection=True, begin=None, orientation=True)\n"
+             "            __init__(brother)\n"
              "\n"
              "   Builds a ChainSilhouetteIterator from the first ViewEdge used for\n"
-             "   iteration and its orientation.\n"
+             "   iteration and its orientation or the copy constructor.\n"
              "\n"
              "   :arg restrict_to_selection: Indicates whether to force the chaining\n"
              "      to stay within the set of selected ViewEdges or not.\n"
@@ -62,11 +63,6 @@ PyDoc_STRVAR(ChainSilhouetteIterator_doc,
              "      false, we'll search over the ViewEdges surrounding the ending\n"
              "      ViewVertex of begin.\n"
              "   :type orientation: bool\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
-             "\n"
              "   :arg brother: A ChainSilhouetteIterator object.\n"
              "   :type brother: :class:`ChainSilhouetteIterator`");
 
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_ChainingIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_ChainingIterator.cpp
index dbd6e8dd09d..d24e1dc527d 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_ChainingIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_ChainingIterator.cpp
@@ -46,11 +46,12 @@ PyDoc_STRVAR(
     "they will be included in the adjacency iterator (i.e, the adjacent\n"
     "iterator will only stop on \"valid\" edges).\n"
     "\n"
-    ".. method:: __init__(restrict_to_selection=True, restrict_to_unvisited=True, begin=None, "
-    "orientation=True)\n"
+    ".. method:: __init__(restrict_to_selection=True, restrict_to_unvisited=True,"
+    "                     begin=None, orientation=True)\n"
+    "            __init__(brother)\n"
     "\n"
     "   Builds a Chaining Iterator from the first ViewEdge used for\n"
-    "   iteration and its orientation.\n"
+    "   iteration and its orientation or by using the copy constructor.\n"
     "\n"
     "   :arg restrict_to_selection: Indicates whether to force the chaining\n"
     "      to stay within the set of selected ViewEdges or not.\n"
@@ -63,11 +64,6 @@ PyDoc_STRVAR(
     "   :arg orientation: The direction to follow to explore the graph.  If\n"
     "      true, the direction indicated by the first ViewEdge is used.\n"
     "   :type orientation: bool\n"
-    "\n"
-    ".. method:: __init__(brother)\n"
-    "\n"
-    "   Copy constructor.\n"
-    "\n"
     "   :arg brother: \n"
     "   :type brother: ChainingIterator");
 
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_CurvePointIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_CurvePointIterator.cpp
index 6c496b0308b..8eac657316e 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_CurvePointIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_CurvePointIterator.cpp
@@ -39,20 +39,14 @@ PyDoc_STRVAR(CurvePointIterator_doc,
              "through the .object attribute.\n"
              "\n"
              ".. method:: __init__()\n"
+             "            __init__(brother)\n"
+             "            __init__(step=0.0)\n"
              "\n"
-             "   Default constructor.\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
+             "   Builds a CurvePointIterator object using either the default constructor,\n"
+             "   copy constructor, or the overloaded constructor.\n"
              "\n"
              "   :arg brother: A CurvePointIterator object.\n"
              "   :type brother: :class:`CurvePointIterator`\n"
-             "\n"
-             ".. method:: __init__(step=0.0)\n"
-             "\n"
-             "   Builds a CurvePointIterator object.\n"
-             "\n"
              "   :arg step: A resampling resolution with which the curve is resampled.\n"
              "      If zero, no resampling is done (i.e., the iterator iterates over\n"
              "      initial vertices).\n"
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp
index 734ed0117f4..f7afc7695ae 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_Interface0DIterator.cpp
@@ -38,17 +38,13 @@ PyDoc_STRVAR(Interface0DIterator_doc,
              "this iterator is always obtained from a 1D element.\n"
              "\n"
              ".. method:: __init__(brother)\n"
+             "            __init__(it)\n"
              "\n"
-             "   Copy constructor.\n"
+             "   Construct a nested Interface0DIterator using either the copy constructor\n"
+             "   or the constructor that takes an he argument of a Function0D.\n"
              "\n"
              "   :arg brother: An Interface0DIterator object.\n"
              "   :type brother: :class:`Interface0DIterator`\n"
-             "\n"
-             ".. method:: __init__(it)\n"
-             "\n"
-             "   Construct a nested Interface0DIterator that can be the argument of\n"
-             "   a Function0D.\n"
-             "\n"
              "   :arg it: An iterator object to be nested.\n"
              "   :type it: :class:`SVertexIterator`, :class:`CurvePointIterator`, or\n"
              "      :class:`StrokeVertexIterator`");
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_SVertexIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_SVertexIterator.cpp
index 4a5927ff6eb..83c504081c1 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_SVertexIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_SVertexIterator.cpp
@@ -32,39 +32,33 @@ extern "C" {
 
 //------------------------INSTANCE METHODS ----------------------------------
 
-PyDoc_STRVAR(SVertexIterator_doc,
-             "Class hierarchy: :class:`Iterator` > :class:`SVertexIterator`\n"
-             "\n"
-             "Class representing an iterator over :class:`SVertex` of a\n"
-             ":class:`ViewEdge`.  An instance of an SVertexIterator can be obtained\n"
-             "from a ViewEdge by calling verticesBegin() or verticesEnd().\n"
-             "\n"
-             ".. method:: __init__()\n"
-             "\n"
-             "   Default constructor.\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
-             "\n"
-             "   :arg brother: An SVertexIterator object.\n"
-             "   :type brother: :class:`SVertexIterator`\n"
-             "\n"
-             ".. method:: __init__(vertex, begin, previous_edge, next_edge, t)\n"
-             "\n"
-             "   Build an SVertexIterator that starts iteration from an SVertex\n"
-             "   object v.\n"
-             "\n"
-             "   :arg vertex: The SVertex from which the iterator starts iteration.\n"
-             "   :type vertex: :class:`SVertex`\n"
-             "   :arg begin: The first SVertex of a ViewEdge.\n"
-             "   :type begin: :class:`SVertex`\n"
-             "   :arg previous_edge: The previous FEdge coming to vertex.\n"
-             "   :type previous_edge: :class:`FEdge`\n"
-             "   :arg next_edge: The next FEdge going out from vertex.\n"
-             "   :type next_edge: :class:`FEdge`\n"
-             "   :arg t: The curvilinear abscissa at vertex.\n"
-             "   :type t: float");
+PyDoc_STRVAR(
+    SVertexIterator_doc,
+    "Class hierarchy: :class:`Iterator` > :class:`SVertexIterator`\n"
+    "\n"
+    "Class representing an iterator over :class:`SVertex` of a\n"
+    ":class:`ViewEdge`.  An instance of an SVertexIterator can be obtained\n"
+    "from a ViewEdge by calling verticesBegin() or verticesEnd().\n"
+    "\n"
+    ".. method:: __init__()\n"
+    "            __init__(brother)\n"
+    "            __init__(vertex, begin, previous_edge, next_edge, t)"
+    "\n"
+    "   Build an SVertexIterator using either the default constructor, copy constructor,\n"
+    "   or the overloaded constructor that starts iteration from an SVertex object vertex.\n"
+    "\n"
+    "   :arg brother: An SVertexIterator object.\n"
+    "   :type brother: :class:`SVertexIterator`\n"
+    "   :arg vertex: The SVertex from which the iterator starts iteration.\n"
+    "   :type vertex: :class:`SVertex`\n"
+    "   :arg begin: The first SVertex of a ViewEdge.\n"
+    "   :type begin: :class:`SVertex`\n"
+    "   :arg previous_edge: The previous FEdge coming to vertex.\n"
+    "   :type previous_edge: :class:`FEdge`\n"
+    "   :arg next_edge: The next FEdge going out from vertex.\n"
+    "   :type next_edge: :class:`FEdge`\n"
+    "   :arg t: The curvilinear abscissa at vertex.\n"
+    "   :type t: float");
 
 static int SVertexIterator_init(BPy_SVertexIterator *self, PyObject *args, PyObject *kwds)
 {
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_StrokeVertexIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_StrokeVertexIterator.cpp
index cda4031240b..e1b24e768e3 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_StrokeVertexIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_StrokeVertexIterator.cpp
@@ -48,12 +48,10 @@ PyDoc_STRVAR(StrokeVertexIterator_doc,
              "by calling Interface0DIterator(it).\n"
              "\n"
              ".. method:: __init__()\n"
+             "            __init__(brother)\n"
              "\n"
-             "   Default constructor.\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
+             "   Creates a :class:`StrokeVertexIterator` using either the\n"
+             "   default constructor or the copy constructor.\n"
              "\n"
              "   :arg brother: A StrokeVertexIterator object.\n"
              "   :type brother: :class:`StrokeVertexIterator`");
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_ViewEdgeIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_ViewEdgeIterator.cpp
index 3d0ed5d5a4d..20134057864 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_ViewEdgeIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_ViewEdgeIterator.cpp
@@ -40,9 +40,10 @@ PyDoc_STRVAR(ViewEdgeIterator_doc,
              "on a given ViewEdge.\n"
              "\n"
              ".. method:: __init__(begin=None, orientation=True)\n"
+             "            __init__(brother)\n"
              "\n"
              "   Builds a ViewEdgeIterator from a starting ViewEdge and its\n"
-             "   orientation.\n"
+             "   orientation or the copy constructor.\n"
              "\n"
              "   :arg begin: The ViewEdge from where to start the iteration.\n"
              "   :type begin: :class:`ViewEdge` or None\n"
@@ -51,11 +52,6 @@ PyDoc_STRVAR(ViewEdgeIterator_doc,
              "      false, we'll search over the ViewEdges surrounding the ending\n"
              "      ViewVertex of begin.\n"
              "   :type orientation: bool\n"
-             "\n"
-             ".. method:: __init__(brother)\n"
-             "\n"
-             "   Copy constructor.\n"
-             "\n"
              "   :arg brother: A ViewEdgeIterator object.\n"
              "   :type brother: :class:`ViewEdgeIterator`");
 
diff --git a/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp b/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
index fe6210468d1..30b7b3ccde5 100644
--- a/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
+++ b/source/blender/freestyle/intern/python/Iterator/BPy_orientedViewEdgeIterator.cpp
@@ -39,12 +39,10 @@ PyDoc_STRVAR(orientedViewEdgeIterator_doc,
              "obtained from a ViewVertex by calling edges_begin() or edges_end().\n"
              "\n"
              ".. method:: __init__()\n"
+             "            __init__(iBrother)\n"
              "\n"
-             "   Default constructor.\n"
-             "\n"
-             ".. method:: __init__(iBrother)\n"
-             "\n"
-             "   Copy constructor.\n"
+             "   Creates an :class:`orientedViewEdgeIterator` using either the\n"
+             "   default constructor or the copy constructor.\n"
              "\n"
              "   :arg iBrother: An orientedViewEdgeIterator object.\n"
              "   :type iBrother: :class:`orientedViewEdgeIterator`");