From 9eeceb4f2897d538abb22d13f253cff3acfdaf18 Mon Sep 17 00:00:00 2001 From: vocx-fc Date: Thu, 6 Feb 2020 00:52:40 -0600 Subject: [PATCH] Draft: improve the README files with links --- src/Mod/Draft/CMakeLists.txt | 6 ++++++ src/Mod/Draft/Resources/README.md | 16 +++++++++++++++ src/Mod/Draft/draftguitools/README.md | 15 ++++++++++---- src/Mod/Draft/draftobjects/README.md | 19 ++++++++++++++--- src/Mod/Draft/drafttaskpanels/README.md | 20 +++++++++++------- src/Mod/Draft/drafttests/README.md | 23 +++++++++++++++++++++ src/Mod/Draft/draftutils/README.md | 23 +++++++++++++++++++++ src/Mod/Draft/draftviewproviders/README.md | 24 +++++++++++++++++++--- 8 files changed, 129 insertions(+), 17 deletions(-) create mode 100644 src/Mod/Draft/Resources/README.md create mode 100644 src/Mod/Draft/drafttests/README.md create mode 100644 src/Mod/Draft/draftutils/README.md diff --git a/src/Mod/Draft/CMakeLists.txt b/src/Mod/Draft/CMakeLists.txt index 161edd634b..58eed4c96d 100644 --- a/src/Mod/Draft/CMakeLists.txt +++ b/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 diff --git a/src/Mod/Draft/Resources/README.md b/src/Mod/Draft/Resources/README.md new file mode 100644 index 0000000000..c9442805f9 --- /dev/null +++ b/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. diff --git a/src/Mod/Draft/draftguitools/README.md b/src/Mod/Draft/draftguitools/README.md index 945a2aa73d..873da82419 100644 --- a/src/Mod/Draft/draftguitools/README.md +++ b/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) diff --git a/src/Mod/Draft/draftobjects/README.md b/src/Mod/Draft/draftobjects/README.md index 7792a0fd94..ebe8650694 100644 --- a/src/Mod/Draft/draftobjects/README.md +++ b/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) diff --git a/src/Mod/Draft/drafttaskpanels/README.md b/src/Mod/Draft/drafttaskpanels/README.md index ea1b29a3e7..404c3c764d 100644 --- a/src/Mod/Draft/drafttaskpanels/README.md +++ b/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) diff --git a/src/Mod/Draft/drafttests/README.md b/src/Mod/Draft/drafttests/README.md new file mode 100644 index 0000000000..d6cac829b1 --- /dev/null +++ b/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) diff --git a/src/Mod/Draft/draftutils/README.md b/src/Mod/Draft/draftutils/README.md new file mode 100644 index 0000000000..52db04d107 --- /dev/null +++ b/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) diff --git a/src/Mod/Draft/draftviewproviders/README.md b/src/Mod/Draft/draftviewproviders/README.md index cbdeb19272..4951a09250 100644 --- a/src/Mod/Draft/draftviewproviders/README.md +++ b/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)