From dd70caa723e5633733f06c8d8ff384d3c9bc5a86 Mon Sep 17 00:00:00 2001 From: vocx-fc Date: Wed, 1 Jul 2020 13:25:18 -0500 Subject: [PATCH] Draft: add modules of draftutils to the proper Doxygen group This includes `gui_utils`, `init_draft_statusbar`, `init_tools`, `messages`, `todo`, `translate`, `utils`. These are added to the `draftutils` Doxygen group so that the functions contained in each module are listed appropriately in the automatically generated documentation. --- src/Mod/Draft/draftutils/groups.py | 12 +++++--- src/Mod/Draft/draftutils/gui_utils.py | 10 +++++-- .../Draft/draftutils/init_draft_statusbar.py | 19 ++++++++----- src/Mod/Draft/draftutils/init_tools.py | 16 +++++++---- src/Mod/Draft/draftutils/messages.py | 16 +++++++---- src/Mod/Draft/draftutils/todo.py | 17 +++++++---- src/Mod/Draft/draftutils/translate.py | 28 +++++++++++-------- src/Mod/Draft/draftutils/units.py | 12 +++++--- src/Mod/Draft/draftutils/utils.py | 18 +++++++----- 9 files changed, 93 insertions(+), 55 deletions(-) diff --git a/src/Mod/Draft/draftutils/groups.py b/src/Mod/Draft/draftutils/groups.py index 8e7ba19c41..ba190541a8 100644 --- a/src/Mod/Draft/draftutils/groups.py +++ b/src/Mod/Draft/draftutils/groups.py @@ -23,18 +23,20 @@ # * USA * # * * # *************************************************************************** -"""Provides utility functions for managing groups in the Draft Workbench. +"""Provides utility functions to do operations with groups. The functions here are also used in the Arch Workbench as some of the objects created with this workbench work like groups. """ ## @package groups -# \ingroup DRAFT -# \brief Provides utility functions for managing groups in the Draft Workbench. +# \ingroup draftutils +# \brief Provides utility functions to do operations with groups. +## \addtogroup draftutils +# @{ import FreeCAD as App - import draftutils.utils as utils + from draftutils.translate import _tr from draftutils.messages import _msg, _err @@ -326,3 +328,5 @@ def getMovableChildren(objectslist, recursive=True): """Return a list of objects with child objects. DEPRECATED.""" utils.use_instead("get_movable_children") return get_movable_children(objectslist, recursive) + +## @} diff --git a/src/Mod/Draft/draftutils/gui_utils.py b/src/Mod/Draft/draftutils/gui_utils.py index bdf7da938c..0de575bbe5 100644 --- a/src/Mod/Draft/draftutils/gui_utils.py +++ b/src/Mod/Draft/draftutils/gui_utils.py @@ -23,7 +23,7 @@ # * USA * # * * # *************************************************************************** -"""Provides GUI utility functions for the Draft Workbench. +"""Provides utility functions that deal with GUI interactions. This module contains auxiliary functions which can be used in other modules of the workbench, and which require @@ -31,9 +31,11 @@ the graphical user interface (GUI), as they access the view providers of the objects or the 3D view. """ ## @package gui_utils -# \ingroup DRAFT -# \brief This module provides GUI utility functions for the Draft Workbench +# \ingroup draftutils +# \brief Provides utility functions that deal with GUI interactions. +## \addtogroup draftutils +# @{ import math import os import six @@ -674,3 +676,5 @@ def migrate_text_display_mode(obj_type="Text", mode="3D text", doc=None): for obj in doc.Objects: if utils.get_type(obj) == obj_type: obj.ViewObject.DisplayMode = mode + +## @} diff --git a/src/Mod/Draft/draftutils/init_draft_statusbar.py b/src/Mod/Draft/draftutils/init_draft_statusbar.py index 0211c6b624..6ef020598a 100644 --- a/src/Mod/Draft/draftutils/init_draft_statusbar.py +++ b/src/Mod/Draft/draftutils/init_draft_statusbar.py @@ -21,16 +21,19 @@ # * USA * # * * # *************************************************************************** -"""Draft Statusbar commands. +"""Provides the initialization code for the workbench's status bar. -This module provide the code for the Draft Statusbar, activated by initGui +The status bar is activated by `InitGui.py` when the workbench is started, +and is populated by various widgets, buttons and menus. """ ## @package init_draft_statusbar -# \ingroup DRAFT -# \brief This module provides the code for the Draft Statusbar. +# \ingroup draftutils +# \brief Provides the initialization code for the workbench's status bar. -from PySide import QtCore -from PySide import QtGui +## \addtogroup draftutils +# @{ +import PySide.QtCore as QtCore +import PySide.QtGui as QtGui from PySide.QtCore import QT_TRANSLATE_NOOP import FreeCAD as App @@ -413,4 +416,6 @@ def hide_draft_statusbar(): # out of the status bar to any other dock area... snap_widget = mw.findChild(QtGui.QToolBar,"draft_snap_widget") if snap_widget: - snap_widget.hide() \ No newline at end of file + snap_widget.hide() + +## @} diff --git a/src/Mod/Draft/draftutils/init_tools.py b/src/Mod/Draft/draftutils/init_tools.py index 4464d9b7c1..12b24b28a5 100644 --- a/src/Mod/Draft/draftutils/init_tools.py +++ b/src/Mod/Draft/draftutils/init_tools.py @@ -20,7 +20,7 @@ # * USA * # * * # *************************************************************************** -"""Provides lists of commands for the Draft Workbench. +"""Provides lists of commands in order to set up toolbars of the workbench. This module returns lists of commands, so that the toolbars can be initialized by Draft, and by other workbenches. @@ -28,9 +28,11 @@ These commands should be defined in `DraftTools`, and in the individual modules in `draftguitools`. """ ## @package init_tools -# \ingroup DRAFT -# \brief This module provides lists of commands for the Draft Workbench. +# \ingroup draftutils +# \brief Provides lists of commands to set up toolbars of the workbench. +## \addtogroup draftutils +# @{ from PySide.QtCore import QT_TRANSLATE_NOOP # Comment out commands that aren't ready to be used @@ -49,7 +51,7 @@ def get_draft_drawing_commands(): def get_draft_annotation_commands(): """Return the annotation commands list.""" return ["Draft_Text", "Draft_Dimension", - "Draft_Label","Draft_AnnotationStyleEditor"] + "Draft_Label", "Draft_AnnotationStyleEditor"] def get_draft_array_commands(): @@ -132,7 +134,7 @@ def init_draft_toolbars(workbench): Parameters ---------- - workbench : Gui.Workbench + workbench: Gui.Workbench The workbench class on which the commands have to be available. If called from within the `Initialize` method of a workbench class defined inside `InitGui.py`, @@ -154,7 +156,7 @@ def init_draft_menus(workbench): Parameters ---------- - workbench : Gui.Workbench + workbench: Gui.Workbench The workbench class on which the commands have to be available. If called from within the `Initialize` method of a workbench class defined inside `InitGui.py`, @@ -169,3 +171,5 @@ def init_draft_menus(workbench): workbench.appendMenu(QT_TRANSLATE_NOOP("Draft", "&Utilities"), get_draft_utility_commands() + get_draft_context_commands()) + +## @} diff --git a/src/Mod/Draft/draftutils/messages.py b/src/Mod/Draft/draftutils/messages.py index e1f8c99cdc..c1a4ecfe35 100644 --- a/src/Mod/Draft/draftutils/messages.py +++ b/src/Mod/Draft/draftutils/messages.py @@ -20,7 +20,7 @@ # * USA * # * * # *************************************************************************** -"""Provide message utility functions for the Draft Workbench. +"""Provides utility functions that wrap around the Console methods. The Console module has long function names, so we define some shorthands that are suitable for use in every workbench. These shorthands also include @@ -28,27 +28,31 @@ a newline character at the end of the string, so it doesn't have to be added manually. """ ## @package messages -# \ingroup DRAFT -# \brief Provide message utility functions for the Draft Workbench. +# \ingroup draftutils +# \brief Provides utility functions that wrap around the Console methods. +## \addtogroup draftutils +# @{ import FreeCAD as App def _msg(text, end="\n"): - """Write messages to console including the line ending.""" + """Write messages to the console including the line ending.""" App.Console.PrintMessage(text + end) def _wrn(text, end="\n"): - """Write warnings to console including the line ending.""" + """Write warnings to the console including the line ending.""" App.Console.PrintWarning(text + end) def _err(text, end="\n"): - """Write errors to console including the line ending.""" + """Write errors to the console including the line ending.""" App.Console.PrintError(text + end) def _log(text, end="\n"): """Write messages to the log file including the line ending.""" App.Console.PrintLog(text + end) + +## @} diff --git a/src/Mod/Draft/draftutils/todo.py b/src/Mod/Draft/draftutils/todo.py index a66e136b1a..4114842263 100644 --- a/src/Mod/Draft/draftutils/todo.py +++ b/src/Mod/Draft/draftutils/todo.py @@ -21,7 +21,7 @@ # * USA * # * * # *************************************************************************** -"""Provides the ToDo class for the Draft Workbench. +"""Provides the ToDo static class to run commands with a time delay. The `ToDo` class is used to delay the commit of commands for later execution. This is necessary when a GUI command needs to manipulate the 3D view @@ -31,16 +31,17 @@ The `ToDo` class essentially calls `QtCore.QTimer.singleShot` to execute the instructions stored in internal lists. """ ## @package todo -# \ingroup DRAFT -# \brief This module provides the ToDo class for the Draft Workbench. +# \ingroup draftutils +# \brief Provides the ToDo static class to run commands with a time delay. import six import sys import traceback -from PySide import QtCore +import PySide.QtCore as QtCore import FreeCAD as App import FreeCADGui as Gui + from draftutils.messages import _msg, _wrn, _err, _log __title__ = "FreeCAD Draft Workbench, Todo class" @@ -50,6 +51,9 @@ __url__ = ["http://www.freecadweb.org"] _DEBUG = 0 _DEBUG_inner = 0 +## \addtogroup draftutils +# @{ + class ToDo: """A static class that delays execution of functions. @@ -281,6 +285,7 @@ class ToDo: ToDo.afteritinerary.append((f, arg)) -# In the past, the class was in lowercase, so we provide a reference -# to it in lowercase, to satisfy the usage of older modules. +# Alias for compatibility with v0.18 and earlier todo = ToDo + +## @} diff --git a/src/Mod/Draft/draftutils/translate.py b/src/Mod/Draft/draftutils/translate.py index ed2ef95394..1e014a8dcf 100644 --- a/src/Mod/Draft/draftutils/translate.py +++ b/src/Mod/Draft/draftutils/translate.py @@ -1,12 +1,3 @@ -"""Provide translate functions for the Draft Workbench. - -This module contains auxiliary functions to translate strings -using the QtCore module. -""" -## @package translate -# \ingroup DRAFT -# \brief Provide translate functions for the Draft Workbench. - # *************************************************************************** # * (c) 2009 Yorik van Havre * # * (c) 2019 Eliud Cabrera Castillo * @@ -30,11 +21,22 @@ using the QtCore module. # * USA * # * * # *************************************************************************** -from PySide import QtCore -from PySide import QtGui +"""Provides utility functions that wrap around the Qt translate functions. + +This module contains auxiliary functions to translate strings +using the QtCore module. +""" +## @package translate +# \ingroup draftutils +# \brief Provides utility functions that wrap around the Qt translate function. + +## \addtogroup draftutils +# @{ +import PySide.QtCore as QtCore +import PySide.QtGui as QtGui import six -Qtranslate = QtGui.QApplication.translate +Qtranslate = QtCore.QCoreApplication.translate # This property only exists in Qt4, which is normally paired # with Python 2. @@ -246,3 +248,5 @@ def _qtr(text): Returns the translated string at runtime. """ return QT_TRANSLATE_NOOP("Draft", text) + +## @} diff --git a/src/Mod/Draft/draftutils/units.py b/src/Mod/Draft/draftutils/units.py index af5f433ec7..e3a1965178 100644 --- a/src/Mod/Draft/draftutils/units.py +++ b/src/Mod/Draft/draftutils/units.py @@ -21,12 +21,14 @@ # * USA * # * * # *************************************************************************** -"""Provides utility functions related to unit handling.""" +"""Provides utility functions to handle quantities and units.""" ## @package units -# \ingroup DRAFT -# \brief Provides utility functions related to unit handling. +# \ingroup draftutils +# \brief Provides utility functions to handle quantities and units. -from PySide import QtCore +## \addtogroup draftutils +# @{ +import PySide.QtCore as QtCore import FreeCAD as App @@ -122,3 +124,5 @@ def display_external(internal_value, displayExternal = display_external + +## @} diff --git a/src/Mod/Draft/draftutils/utils.py b/src/Mod/Draft/draftutils/utils.py index e1932922ef..699ef51c91 100644 --- a/src/Mod/Draft/draftutils/utils.py +++ b/src/Mod/Draft/draftutils/utils.py @@ -23,21 +23,22 @@ # * USA * # * * # *************************************************************************** -"""Provides utility functions for the Draft Workbench. +"""Provides general utility functions used throughout the workbench. This module contains auxiliary functions which can be used in other modules of the workbench, and which don't require the graphical user interface (GUI). """ ## @package utils -# \ingroup DRAFT -# \brief This module provides utility functions for the Draft Workbench +# \ingroup draftutils +# \brief Provides general utility functions used throughout the workbench. +## \addtogroup draftutils +# @{ import os -from PySide import QtCore +import PySide.QtCore as QtCore import FreeCAD as App -import Draft_rc from draftutils.messages import _msg, _wrn, _err, _log from draftutils.translate import _tr @@ -47,9 +48,10 @@ from draftutils.translate import _tr # in gui_utils if App.GuiUp: import FreeCADGui as Gui + import Draft_rc -# The module is used to prevent complaints from code checkers (flake8) -True if Draft_rc else False + # The module is used to prevent complaints from code checkers (flake8) + True if Draft_rc else False param = App.ParamGet("User parameter:BaseApp/Preferences/Mod/Draft") @@ -1122,3 +1124,5 @@ def use_instead(function, version=""): else: _wrn(_tr(text2) + _tr(text3) + "'{}'.".format(function)) + +## @}