Draft: add description of draftmake package

These modules provide the functions that are used to create
the scripted objects defined within the workbench.

The functions import and use the proxy classes
and viewprovider classes in `draftobjects`
and `draftviewproviders`.

These functions are imported in the main `Draft.py` module
so they form part of the public programming interface (API)
of the workbench.

src/Mod/Draft/CMakeLists.txt

@@ -95,6 +95,7 @@ SET(Draft_make_functions
     draftmake/make_sketch.py
     draftmake/make_wire.py
     draftmake/make_wpproxy.py
+    draftmake/README.md
 )
 
 SET(Draft_objects

src/Mod/Draft/draftmake/README.md

@@ -0,0 +1,38 @@
+2020 May
+
+These modules contain the basic functions to create custom "scripted objects"
+defined within the workbench.
+
+Each scripted object has a "make function" like `make_rectangle`,
+a proxy class like `Rectangle`, and a viewprovider class
+like `ViewProviderRectangle`.
+Each make function should import the two corresponding classes
+in order to create a new object with the correct data
+and visual properties for that object.
+These classes should be defined in the modules in `draftobjects/`
+and `draftviewproviders/`.
+
+The make functions can be used in both graphical and non-graphical
+modes (terminal only); in the latter case the viewprovider is not used.
+The functions are also used internally by the graphical "GuiCommands"
+(buttons, menu actions) defined in the modules in `draftguitools/`
+and `drafttaskpanels/`.
+
+These make functions were previously defined in the `Draft.py` module,
+which was very large. Now `Draft.py` just loads the individual modules
+in order to provide these functions under the `Draft` namespace.
+
+```py
+import Draft
+
+new_obj1 = Draft.make_rectangle(...)
+new_obj2 = Draft.make_circle(...)
+new_obj3 = Draft.make_line(...)
+```
+
+The functions in the `Draft` namespace are considered to be the public
+application programming interface (API) of the workbench, and should be
+usable in scripts, macros, and other workbenches.
+
+For more information see the thread:
+[[Discussion] Splitting Draft tools into their own modules](https://forum.freecadweb.org/viewtopic.php?f=23&t=38593&start=10#p341298)

src/Mod/Draft/draftmake/__init__.py

@@ -1,3 +1,82 @@
-"""Functions that to create custom scripted Draft objects.
+# ***************************************************************************
+# *   (c) 2020 Carlo Pavan <carlopav@gmail.com>                             *
+# *   (c) 2020 Eliud Cabrera Castillo <e.cabrera-castillo@tum.de>           *
+# *                                                                         *
+# *   This file is part of the FreeCAD CAx development system.              *
+# *                                                                         *
+# *   This program is free software; you can redistribute it and/or modify  *
+# *   it under the terms of the GNU Lesser General Public License (LGPL)    *
+# *   as published by the Free Software Foundation; either version 2 of     *
+# *   the License, or (at your option) any later version.                   *
+# *   for detail see the LICENCE text file.                                 *
+# *                                                                         *
+# *   FreeCAD is distributed in the hope that it will be useful,            *
+# *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
+# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
+# *   GNU Library General Public License for more details.                  *
+# *                                                                         *
+# *   You should have received a copy of the GNU Library General Public     *
+# *   License along with FreeCAD; if not, write to the Free Software        *
+# *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
+# *   USA                                                                   *
+# *                                                                         *
+# ***************************************************************************
+"""Modules that contain functions to create custom scripted objects.
 
+These functions represent the basic application programming interface (API)
+of the Draft Workbench to create custom objects.
+
+These functions first create a simple, extensible object defined in C++,
+for example, `Part::FeaturePython` or `Part::Part2DObjectPython`,
+and then assign a custom proxy class to define its data properties,
+and a custom viewprovider class to define its visual properties.
+
+The proxy class is imported from `draftobjects` and the corresponding
+viewprovider from `draftviewproviders`.
+
+::
+
+    import FreeCAD as App
+    import draftobjects.my_obj as my_obj
+    import draftviewproviders.view_my_obj as view_my_obj
+
+    def make_function(input_data):
+        doc = App.ActiveDocument
+        new_obj = doc.addObject("Part::Part2DObjectPython",
+                                "New_obj")
+        my_obj.Obj(new_obj)
+
+        if App.GuiUp:
+            view_my_obj.ViewProviderObj(new_obj.ViewObject)
+
+        return new_obj
+
+Assigning the viewprovider class is only possible if the graphical interface
+is available. In a terminal-only session the viewproviders are not accessible
+because the `ViewObject` attribute does not exist.
+
+If an object is created and saved in a console-only session,
+the object will not have the custom viewprovider when the file is opened
+in the GUI version of the program; it will only have a basic viewprovider
+associated to the base C++ object.
+
+If needed, the custom viewprovider can be assigned after opening
+the GUI version of the program; then the object will have access
+to additional visual properties.
+
+::
+
+    import Draft
+    Draft.ViewProviderDraft(new_obj.ViewObject)
+
+Most Draft objects are based on two base `Part` objects
+that are able to handle a `Part::TopoShape`.
+
+- `Part::Part2DObjectPython` if they should handle only 2D shapes, and
+- `Part::FeaturePython` if they should handle any type of shape (2D or 3D).
+
+Generic objects that don't need to handle shapes but which
+can have other properties like `App::PropertyPlacement`,
+or which can interact with the 3D view through Coin,
+can be based on the simple `App::FeaturePython` object.
 """