Draft: improve the README files with links

src/Mod/Draft/CMakeLists.txt

@@ -46,6 +46,7 @@ SET(Draft_tests
     drafttests/test_oca.py
     drafttests/test_airfoildat.py
     drafttests/draft_test_objects.py
+    drafttests/README.md
 )
 
 SET(Draft_utilities
@@ -56,6 +57,7 @@ SET(Draft_utilities
     draftutils/todo.py
     draftutils/translate.py
     draftutils/messages.py
+    draftutils/README.md
 )
 
 SET(Draft_objects
@@ -64,6 +66,7 @@ SET(Draft_objects
     draftobjects/orthoarray.py
     draftobjects/polararray.py
     draftobjects/arc_3points.py
+    draftobjects/README.md
 )
 
 SET(Draft_view_providers
@@ -71,6 +74,7 @@ SET(Draft_view_providers
     draftviewproviders/view_circulararray.py
     draftviewproviders/view_orthoarray.py
     draftviewproviders/view_polararray.py
+    draftviewproviders/README.md
 )
 
 SET(Draft_GUI_tools
@@ -80,6 +84,7 @@ SET(Draft_GUI_tools
     draftguitools/gui_orthoarray.py
     draftguitools/gui_polararray.py
     draftguitools/gui_arrays.py
+    draftguitools/README.md
 )
 
 SET(Draft_task_panels
@@ -87,6 +92,7 @@ SET(Draft_task_panels
     drafttaskpanels/task_circulararray.py
     drafttaskpanels/task_orthoarray.py
     drafttaskpanels/task_polararray.py
+    drafttaskpanels/README.md
 )
 
 SET(Draft_SRCS_all

src/Mod/Draft/Resources/README.md

@@ -0,0 +1,16 @@
+2020 February
+
+These files provide read only resources for the workbench.
+- `icons/`: SVG images to use as icons.
+- `patterns/`: in SVG, to fill closed shapes.
+- `translations/`: translation files generated from Qt tools and Crowdin.
+- `ui/`: Qt user interface files made with QtCreator, and which connect
+to the corresponding modules in `drafttaskpanels/`.
+
+All files in this directory should be read-only, as they are not meant
+to be executed. They are only meant to be read by the program.
+
+The `Draft.qrc` file lists all resources. This file is used
+to compile the resources into a single `Draft_rc.py` file
+which can then be imported in the modules of the workbench
+to provide the correct resource at run time.

src/Mod/Draft/draftguitools/README.md

@@ -1,13 +1,20 @@
 2020 February
 
-These files define the GuiCommands, that is, actions called in a graphical
-way, either buttons, menu entries, or context commands.
+These files define the "GuiCommands", that is, classes called in a graphical
+way through either buttons, menu entries, or context actions.
+They don't define the graphical interfaces themselves, they just setup
+tools that connect with FreeCAD's C++ code.
 
 These tools should be split from the big `DraftTools.py` module.
+The classes defined here internally use the GUI-less functions
+defined in `Draft.py`, or in the newer modules under `draftobjects/`.
 
-These tools are initialized by `InitGui.py`, and require the graphical
+These tools are loaded by `InitGui.py`, and thus require the graphical
 interface to exist.
 
 Those commands that require a "task panel" call the respective module
-and class in `drafttaskpanels/`.
+and class in `drafttaskpanels/`. The task panel interfaces themselves
+are defined inside the `Resources/ui/` files created with QtCreator.
 
+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/draftobjects/README.md

@@ -1,7 +1,20 @@
 2020 February
 
-At the moment these object functions aren't used.
+These files define modules to create specific "scripted objects"
+from the terminal, that is, without requiring the graphical interface.
+They define both a creation command such as `make_arc`, and the corresponding
+proxy class, such as `Arc`. The corresponding view provider class
+should be defined in the modules in `draftviewproviders/`.
 
-When the Draft tools are eventually split into individual modules,
-the code of the object creation functions should be placed here.
+These modules should be split from the big `Draft.py` module.
 
+At the moment the files in this directory aren't really used,
+but are used as placeholders for when the migration of classes and functions
+happens.
+
+The creation functions should be used internally by the "GuiCommands"
+defined in `DraftTools.py` or in the newer modules under `draftguitools/`
+and `drafttaskpanels/`.
+
+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/drafttaskpanels/README.md

@@ -1,13 +1,19 @@
 2020 February
 
-These files provide the logic behind the task panel of the GuiCommands
+These files provide the logic behind the task panels of the "GuiCommands"
 defined in `draftguitools/`.
 
-The task panel graphical interface is properly defined in
-the `Resources/ui/` files, which are made with QtCreator.
+These files should not have code to create the task panel windows
+and widgets manually. These interfaces should be properly defined
+in the `.ui` files made with QtCreator and placed inside
+the `Resources/ui/` directory.
 
-There are many commands which aren't defined in `draftguitools/`.
-These are defined in the big `DraftGui.py` module, which needs to be split
-into individual GuiCommands, and each should have its own dedicated
-`.ui` file.
+There are many commands which aren't defined in `draftguitools/`,
+and which therefore don't have an individual task panel.
+These commands are defined in the big `DraftTools.py` file,
+and their task panels are manually written in the large `DraftGui.py` module.
+Therefore, these commands should be split into individual files,
+and each should have its own `.ui` file.
 
+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/drafttests/README.md

@@ -0,0 +1,23 @@
+2020 February
+
+These files provide the unit tests classes based on the standard Python
+`unittest` module.
+
+These files should be imported from the main `TestDraft.py` module
+which is the one registered in the program in `InitGui.py`.
+
+Each module should define a class derived from `unittest.TestCase`,
+and the individual methods of the class correspond to the individual
+unit tests which try a specific function in the workbench.
+
+The tests should be callable from the terminal.
+```
+program -t TestDraft  # all tests
+program -t drafttests.test_creation  # only creation functions
+
+# A specific test
+program -t drafttests.test_creation.DraftCreation.test_line
+```
+
+For more information see the thread:
+[New unit tests for Draft Workbench](https://forum.freecadweb.org/viewtopic.php?f=23&t=40405)

src/Mod/Draft/draftutils/README.md

@@ -0,0 +1,23 @@
+2020 February
+
+These files provide auxiliary functions used by the Draft workbench.
+Previously most of these were in `Draft.py`, `DraftTools.py`
+and `DraftGui.py`.
+
+In here we want modules with generic functions that can be used everywhere
+in the workbench. We want these tools to depend only on standard modules
+so that there are no circular dependencies, and so that they can be used
+by all functions and graphical commands in this workbench
+and possibly other workbenches.
+- `utils`: basic functions
+- `messages`: used to print messages
+- `translate`: used to translate texts
+- `init_tools`: used to initialize the workbench (toolbars and menus)
+- `todo`: used to delay execution of certain graphical commands
+
+Some auxiliary functions require that the graphical interface is loaded
+as they deal with scripted objects' view providers or the 3D view.
+- `gui_utils`: basic functions dealing with the graphical interface
+
+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/draftviewproviders/README.md

@@ -1,7 +1,25 @@
 2020 February
 
-At the moment these view providers aren't used at all.
+These files define the view provider classes of the "scripted objects"
+defined by the workbench. These scripted objects are originally
+defined in the big `Draft.py` file.
 
-When the Draft tools are eventually split into individual modules,
-the code of the view providers should be placed here.
+Each scripted object has a creation command like `make_arc`, 
+a proxy class like `Arc`, and a view provider like `ViewProviderArc`.
+The view providers define the code that indicates how they are displayed
+in the tree view and in the 3D view, and visual properties
+such as line thickness, line color, face color, and transparency.
+These properties are only available when the graphical interface exists,
+otherwise they are ignored.
 
+Each scripted object in `draftobjects/` should import its corresponding
+view provider from this directory as long the graphical interface
+is available.
+
+These modules should be split from the big `Draft.py` module.
+
+At the moment the files in this directory aren't really used,
+but are used as placeholders for when the migration of classes happens.
+
+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)