From: Renaud NEDELEC <renaud.nedelec@opencascade.com>
Date: Mon, 9 Nov 2015 15:42:28 +0000 (+0100)
Subject: [PythonAPI / doc] possible doc structuration example on extrusion feature
X-Git-Tag: V_2.1.0~206^2~4
X-Git-Url: http://git.salome-platform.org/gitweb/?a=commitdiff_plain;h=78b4ff3254e90bc9ee8d82a217e514404dfe8b9e;p=modules%2Fshaper.git

[PythonAPI / doc] possible doc structuration example on extrusion feature
the documentation has been formated for sphinx usage
and Extrusion doc has been moved to addExtrusion
---

diff --git a/src/PythonAPI/doc/source/conf.py b/src/PythonAPI/doc/source/conf.py
index 9c9b82b11..7e213bc64 100644
--- a/src/PythonAPI/doc/source/conf.py
+++ b/src/PythonAPI/doc/source/conf.py
@@ -54,7 +54,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Shaper python API'
-copyright = u'2015, Renaud Nédélec'
+copyright = u'2014-20xx CEA/DEN, EDF R&D'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/src/PythonAPI/doc/source/extrusion.rst b/src/PythonAPI/doc/source/extrusion.rst
index 292568272..25d77281c 100644
--- a/src/PythonAPI/doc/source/extrusion.rst
+++ b/src/PythonAPI/doc/source/extrusion.rst
@@ -1,5 +1,40 @@
 Extrusion
 ---------
 
-.. automodule:: model.features.extrusion
+.. testsetup::
+
+   import model
+   model.begin()
+   partset = model.moduleDocument()
+   part = model.addPart(partset).document()
+   plane = model.defaultPlane("XOY")
+   sketch = model.addSketch(part, plane)
+   p1 = sketch.addPoint(0, 0)
+   p2 = sketch.addPoint(0, 1)
+   p3 = sketch.addPoint(1, 1)
+   p4 = sketch.addPoint(1, 0)
+   sketch.addPolygon(p1.pointData(), p2.pointData(), p3.pointData(), p4.pointData())
+
+Provided that a sketch has been created before an extrusion can then be created
+by the following code:
+
+.. doctest::
+   
+   >>> base = sketch.selectFace()
+   >>> extrusion = model.addExtrusion(part, base, 10)
+   >>> # Modification of the extrusion
+   >>> extrusion.setSize(20)
+   
+All the ways to create an extrusion and the data access and modification methods 
+of the extrusion are documented below
+
+Create an extrusion
+...................
+   
+.. autofunction:: model.features.extrusion.addExtrusion
+
+Extrusion object
+................
+
+.. autoclass:: model.features.extrusion.Extrusion
    :members:
diff --git a/src/PythonAPI/doc/source/index.rst b/src/PythonAPI/doc/source/index.rst
index 749600721..ef5dc2733 100644
--- a/src/PythonAPI/doc/source/index.rst
+++ b/src/PythonAPI/doc/source/index.rst
@@ -27,9 +27,15 @@ with the parametric API will typically begin with a code like below:
    >>> sketch = model.addSketch(part, plane)
    >>> line = sketch.addLine(0, 0, 0, 1)
 
+Features
+........
+
+This API provides functions for creating the features listed below.
+These functions return an interface to the feature that allow 
+to modify the feature and retrieve data from it.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    sketcher
    extrusion
diff --git a/src/PythonAPI/doc/source/sketcher.rst b/src/PythonAPI/doc/source/sketcher.rst
index cb8b2b6cb..3fb415927 100644
--- a/src/PythonAPI/doc/source/sketcher.rst
+++ b/src/PythonAPI/doc/source/sketcher.rst
@@ -12,8 +12,8 @@ Create a sketch
 .. autosummary::
    addSketch
 
-Add geometries to the sketch
-----------------------------
+Add geometries
+--------------
 
 .. autosummary::
 
@@ -30,8 +30,8 @@ Set constraints
    Sketch.setRadius
    Sketch.setParallel
 
-Detailed description of sketch interface
-----------------------------------------
+Detailed description
+--------------------
 
 Add a sketch to the document
 ............................
diff --git a/src/PythonAPI/model/features/extrusion.py b/src/PythonAPI/model/features/extrusion.py
index 1ecccf996..a93cf4942 100644
--- a/src/PythonAPI/model/features/extrusion.py
+++ b/src/PythonAPI/model/features/extrusion.py
@@ -9,8 +9,35 @@ from model import Selection
 
 def addExtrusion(part, *args):
     """Add an Extrusion feature to the Part and return Extrusion.
-
-    Pass all args to Extrusion __init__ function.
+    
+    This function has *3 signatures*:
+    
+    .. function:: addExtrusion(base, size)
+    
+    Arguments:
+        base(str, Sketch or list): base object(s)
+        size(double): size of the extrusion, the side is decided by the sign
+    
+    .. function:: addExtrusion(base, to_size, from_size)
+    
+    Arguments:
+        base(str, Sketch or list): base object(s)
+        to_size(double): upper size of the extrusion
+        from_size(double): lower size of the extrusion
+    
+    .. function:: addExtrusion(base, to_object, to_offset, from_object, from_offset)
+    
+    Arguments:
+        base(str, Sketch or list): base object(s)
+        to_object(plane): upper object
+        to_offset(double): offset from upper object
+        from_object(plane): lower plane
+        from_offset(double): offset from lower plane
+        
+    In all three cases the function returns an extrusion object
+    
+    Returns:
+        Extrusion: extrusion object
     """
     assert(args)
     feature = part.addFeature("Extrusion")
@@ -19,28 +46,28 @@ def addExtrusion(part, *args):
 
 class Extrusion(Interface):
     """Interface class for Extrusion feature.
-
-    Extrusion(feature) -> feature interface without initialization
-    Extrusion(feature, base, size) ->
-        feature interface initialized from arguments:
-        - base -- name, sketch or list of names and sketches
-        - size -- if positive -> to_size, if negative -> from_size
-    Extrusion(feature, base, to_size, from_size) ->
-        feature interface initialized from arguments:
-        - base -- name, sketch or list of names and sketches
-        - to_size -- upper size
-        - from_size -- lower size
-    Extrusion(feature, base, to_object, to_offset, from_object, from_offset) ->
-        feature interface initialized from arguments:
-        - base -- name, sketch or list of names and sketches
-        - to_object -- upper object (plane)
-        - to_offset -- offset from upper object
-        - from_object -- lower object (plane)
-        - from_offset -- offset from lower object
     """
 
     def __init__(self, feature, *args):
-        """x.__init__(...) initializes x; see x.__class__.__doc__ for signature"""
+        """
+        Extrusion(feature) -> feature interface without initialization
+        Extrusion(feature, base, size) ->
+            feature interface initialized from arguments:
+            - base -- name, sketch or list of names and sketches
+            - size -- if positive -> to_size, if negative -> from_size
+        Extrusion(feature, base, to_size, from_size) ->
+            feature interface initialized from arguments:
+            - base -- name, sketch or list of names and sketches
+            - to_size -- upper size
+            - from_size -- lower size
+        Extrusion(feature, base, to_object, to_offset, from_object, from_offset) ->
+            feature interface initialized from arguments:
+            - base -- name, sketch or list of names and sketches
+            - to_object -- upper object (plane)
+            - to_offset -- offset from upper object
+            - from_object -- lower object (plane)
+            - from_offset -- offset from lower object
+        """
         Interface.__init__(self, feature)
         assert(self._feature.getKind() == "Extrusion")
 
diff --git a/src/PythonAPI/model/sketcher/sketch.py b/src/PythonAPI/model/sketcher/sketch.py
index 7d5311e39..aac77596c 100644
--- a/src/PythonAPI/model/sketcher/sketch.py
+++ b/src/PythonAPI/model/sketcher/sketch.py
@@ -19,6 +19,10 @@ Example of code:
    >>> plane = model.defaultPlane("XOY")
    >>> sketch = model.addSketch(part, plane)
    >>> line = sketch.addLine(0, 0, 0, 1)
+   >>> line.endPointData().x()
+   0.0
+   >>> line.endPointData().y()
+   1.0
 """
 
 from ModelAPI import modelAPI_ResultConstruction, featureToCompositeFeature