From 46eee244eac1face653cce6a9f72e57671fadbbb Mon Sep 17 00:00:00 2001
From: Renaud NEDELEC <renaud.nedelec@opencascade.com>
Date: Fri, 6 Nov 2015 17:32:45 +0100
Subject: [PATCH] [PythonAPI / doc] structuration of documentation

---
 src/PythonAPI/doc/source/conf.py       |  1 +
 src/PythonAPI/doc/source/extrusion.rst |  4 +-
 src/PythonAPI/doc/source/index.rst     | 40 ++++++++++++--------
 src/PythonAPI/doc/source/sketcher.rst  | 51 ++++++++++++++++----------
 src/PythonAPI/model/sketcher/sketch.py |  3 +-
 5 files changed, 60 insertions(+), 39 deletions(-)

diff --git a/src/PythonAPI/doc/source/conf.py b/src/PythonAPI/doc/source/conf.py
index 817856ff0..9c9b82b11 100644
--- a/src/PythonAPI/doc/source/conf.py
+++ b/src/PythonAPI/doc/source/conf.py
@@ -37,6 +37,7 @@ extensions = [
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'sphinx.ext.autosummary',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
diff --git a/src/PythonAPI/doc/source/extrusion.rst b/src/PythonAPI/doc/source/extrusion.rst
index 7e59d8ef7..292568272 100644
--- a/src/PythonAPI/doc/source/extrusion.rst
+++ b/src/PythonAPI/doc/source/extrusion.rst
@@ -1,5 +1,5 @@
-:mod:`model.features.extrusion` -- Extrusion feature interface
---------------------------------------------------------------
+Extrusion
+---------
 
 .. automodule:: model.features.extrusion
    :members:
diff --git a/src/PythonAPI/doc/source/index.rst b/src/PythonAPI/doc/source/index.rst
index 823cb5252..749600721 100644
--- a/src/PythonAPI/doc/source/index.rst
+++ b/src/PythonAPI/doc/source/index.rst
@@ -1,27 +1,37 @@
-.. Shaper python API documentation master file, created by
-   sphinx-quickstart on Thu Oct 15 11:55:42 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+Shaper textual interface documentation
+======================================
 
-Welcome to Shaper python API's documentation!
-=============================================
+Shaper provides two different textual interfaces that allows you to create
+models through python scripts:
 
+* a "direct" API, which allows you to create geometrical objects
+  without any parametric considerations
 
-Sketching operations
---------------------
+* a "parametric" API, which is very close to what is done
+  in the graphical interface and allows you to recalculate a model
+  when a parameter is changed 
 
-.. toctree::
-   :maxdepth: 2
+Parametric API
+--------------
 
-   sketcher
-   arc
+This API is implemented in the model Python package. A script written
+with the parametric API will typically begin with a code like below:
+
+.. doctest:: 
+
+   >>> import model
+   >>> model.begin()
+   >>> partset = model.moduleDocument()
+   >>> part = model.addPart(partset).document()
+   >>> plane = model.defaultPlane("XOY")
+   >>> sketch = model.addSketch(part, plane)
+   >>> line = sketch.addLine(0, 0, 0, 1)
 
-Features
---------
 
 .. toctree::
    :maxdepth: 2
 
+   sketcher
    extrusion
 
 
@@ -31,5 +41,3 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
diff --git a/src/PythonAPI/doc/source/sketcher.rst b/src/PythonAPI/doc/source/sketcher.rst
index 86f89dd5f..cb8b2b6cb 100644
--- a/src/PythonAPI/doc/source/sketcher.rst
+++ b/src/PythonAPI/doc/source/sketcher.rst
@@ -1,5 +1,5 @@
-:mod:`model.sketcher.sketch` -- Sketch interface
-================================================
+Sketch interface
+================
 
 .. automodule:: model.sketcher.sketch
 .. :members:
@@ -9,30 +9,43 @@
 Create a sketch
 ---------------
 
-.. autofunction:: addSketch
+.. autosummary::
+   addSketch
 
-Modify the sketch
------------------
+Add geometries to the sketch
+----------------------------
 
-The sketch object returned by the above described :meth:`~model.sketcher.sketch.addSketch` method
-provides an interface for:
+.. autosummary::
 
-  * creating geometries
-  * setting and modifying constraints
+   Sketch.addPoint
+   Sketch.addLine
+   Sketch.addArc
+   Sketch.addCircle
 
-Create geometries
-.................
+Set constraints
+---------------
 
-.. automethod:: Sketch.addPoint
-.. automethod:: Sketch.addLine
-.. automethod:: Sketch.addArc
-.. automethod:: Sketch.addCircle
+.. autosummary::
 
+   Sketch.setRadius
+   Sketch.setParallel
 
-Set constraints
-...............
+Detailed description of sketch interface
+----------------------------------------
 
-.. automethod:: Sketch.setRadius
-.. automethod:: Sketch.setParallel
+Add a sketch to the document
+............................
 
+.. autofunction:: addSketch
+
+Sketch object
+.............
+
+The sketch object returned by the above described :meth:`~model.sketcher.sketch.addSketch` method
+provides an interface for:
+
+  * creating geometries
+  * setting and modifying constraints
 
+.. autoclass:: Sketch
+   :members:
diff --git a/src/PythonAPI/model/sketcher/sketch.py b/src/PythonAPI/model/sketcher/sketch.py
index 24268b4c5..7d5311e39 100644
--- a/src/PythonAPI/model/sketcher/sketch.py
+++ b/src/PythonAPI/model/sketcher/sketch.py
@@ -2,8 +2,7 @@
 #         finalized by Renaud Nedelec and Sergey Pokhodenko
 # Copyright (C) 2014-20xx CEA/DEN, EDF R&D
 
-"""Sketcher interface
-
+"""Sketcher interface.
 This interface allows to add a sketch
 in a part or partset.
 The created sketch object provides all the needed methods 
-- 
2.39.2