From 69311479e5552f9a29b48003a464beb0054ab85d Mon Sep 17 00:00:00 2001 From: David Daish Date: Tue, 7 Apr 2020 14:20:34 +1200 Subject: [PATCH] Added docstrings for arch project, and corrected some doc mistakes. --- src/Mod/Arch/ArchFloor.py | 44 +++++++++++-------- src/Mod/Arch/ArchProject.py | 86 +++++++++++++++++++++++++++++++++++-- src/Mod/Arch/ArchWall.py | 6 ++- 3 files changed, 114 insertions(+), 22 deletions(-) diff --git a/src/Mod/Arch/ArchFloor.py b/src/Mod/Arch/ArchFloor.py index 4ffd2241d3..b15e0e05e6 100644 --- a/src/Mod/Arch/ArchFloor.py +++ b/src/Mod/Arch/ArchFloor.py @@ -60,14 +60,20 @@ def makeFloor(objectslist=None,baseobj=None,name="Floor"): Parameters ---------- - objectslist: list of + objectslist: list of , optional The objects to add to the new floor. baseobj: Unused. - name: str + name: str, optional The Label for the new floor. + + Returns + ------- + + The created floor. """ + if not FreeCAD.ActiveDocument: FreeCAD.Console.PrintError("No active document. Aborting\n") return @@ -86,18 +92,18 @@ class _CommandFloor: A tool for creating Arch floors. - Creates a floor from the objects selected by the user. Excludes objects - that appear higher in the object heirarchy, such as sites or buildings. If - free linking is enabled in the Arch preferenecs, allows higher heirarchy - objects to be part of floors. + Creates a floor from the objects selected by the user, if any. Excludes + objects that appear higher in the object heirarchy, such as sites or + buildings. If free linking is enabled in the Arch preferenecs, allows + higher heirarchy objects to be part of floors. - Find documentation on the end user usage of Arch Wall here: + Find documentation on the end user usage of Arch Floor here: https://wiki.freecadweb.org/Arch_Floor """ def GetResources(self): - """Returns a dictionary with the visual aspects of the Arch Wall tool.""" + """Returns a dictionary with the visual aspects of the Arch Floor tool.""" return {'Pixmap' : 'Arch_Floor', 'MenuText': QT_TRANSLATE_NOOP("Arch_Floor","Level"), @@ -105,7 +111,7 @@ class _CommandFloor: 'ToolTip': QT_TRANSLATE_NOOP("Arch_Floor","Creates a Building Part object that represents a level, including selected objects")} def IsActive(self): - """Determines whether or not the Arch Wall tool is active. + """Determines whether or not the Arch Floor tool is active. Inactive commands are indicated by a greyed-out icon in the menus and toolbars. """ @@ -115,7 +121,7 @@ class _CommandFloor: def Activated(self): """Executed when Arch Floor is called. - Creates a floor from the objects selected by the user. Excludes + Creates a floor from the objects selected by the user, if any. Excludes objects that appear higher in the object heirarchy, such as sites or buildings. If free linking is enabled in the Arch preferenecs, allows higher heirarchy objects to be part of floors. @@ -159,7 +165,11 @@ Floor creation aborted.") + "\n" class _Floor(ArchIFC.IfcProduct): - """The Floor object.""" + """The Floor object. + + Turns a into a floor object, then + takes a list of objects to own as it's children. + """ def __init__(self,obj): """Initalises the floor. @@ -167,7 +177,7 @@ class _Floor(ArchIFC.IfcProduct): The floor can be based off either a group, or a python feature. Learn more about groups here: https://wiki.freecadweb.org/Std_Group - Adds the parameters of a floor, and sets it's IFC type. + Adds the properties of a floor, and sets it's IFC type. Parameters ---------- @@ -297,17 +307,17 @@ class _Floor(ArchIFC.IfcProduct): class _ViewProviderFloor: - """A View Provider for the Floor object""" + """A View Provider for the Floor object.""" def __init__(self,vobj): - """Initialises the Component view provider. + """Initialises the floor view provider. Registers the Proxy as this class object. Parameters ---------- vobj: - The view provider to turn into an Component view provider. + The view provider to turn into a floor view provider. """ vobj.Proxy = self @@ -366,10 +376,10 @@ class _ViewProviderFloor: return None def setupContextMenu(self,vobj,menu): - """Adds the component specific options to the context menu. + """Adds the floor specific options to the context menu. The context menu is the drop down menu that opens when the user right - clicks on the component in the tree view. + clicks on the floor in the tree view. Adds a menu choice to convert the floor to an Arch Building Part with the ArchBuildingPart.convertFloors function. diff --git a/src/Mod/Arch/ArchProject.py b/src/Mod/Arch/ArchProject.py index b7776bb125..97b3931ac9 100644 --- a/src/Mod/Arch/ArchProject.py +++ b/src/Mod/Arch/ArchProject.py @@ -42,10 +42,30 @@ else: __title__="FreeCAD Project" __author__ = "Yorik van Havre" __url__ = "http://www.freecadweb.org" +__doc__ = """This module provides tools to build Project objects. + Project objects are objects specifically for better IFC + compatability, allowing the user to tweak certain IFC + relevant values. + """ def makeProject(sites=None, name="Project"): + """Creates an Arch project. - '''makeProject(sites): creates a project aggregating the list of sites.''' + If sites are provided, will add them as children of the new project. + + Parameters + ---------- + sites: list of , optional + Sites to add as children of the project. Ultimately this could be + anything, however. + name: str, optional + The label for the project. + + Returns + ------- + + The created project. + """ if not FreeCAD.ActiveDocument: return FreeCAD.Console.PrintError("No active document. Aborting\n") @@ -61,19 +81,38 @@ def makeProject(sites=None, name="Project"): return obj class _CommandProject: + """The command definition for the Arch workbench's gui tool, Arch Project. - "the Arch Project command definition" + A tool for creating Arch projects. + + Creates a project from the objects selected by the user that have the Site + IfcType, if any. + + Find documentation on the end user usage of Arch Project here: + https://wiki.freecadweb.org/Arch_Project + """ def GetResources(self): + """Returns a dictionary with the visual aspects of the Arch Project tool.""" return {'Pixmap' : 'Arch_Project', 'MenuText': QT_TRANSLATE_NOOP("Arch_Project", "Project"), 'Accel': "P, O", 'ToolTip': QT_TRANSLATE_NOOP("Arch_Project", "Creates a project entity aggregating the selected sites.")} def IsActive(self): + """Determines whether or not the Arch Project tool is active. + + Inactive commands are indicated by a greyed-out icon in the menus and toolbars. + """ return not FreeCAD.ActiveDocument is None def Activated(self): + """Executed when Arch Project is called. + + Creates a project from the objects selected by the user that have the + Site IfcType, if any. + """ + selection = FreeCADGui.Selection.getSelection() siteobj = [] @@ -94,13 +133,34 @@ class _CommandProject: FreeCAD.ActiveDocument.recompute() class _Project(ArchIFC.IfcContext): + """The project object. + + Takes a , and turns it into a Project. Then takes a + list of Arch sites to own as it's children. + """ def __init__(self, obj): + """Initalises the project. + + Adds the properties of a project, and sets it's IFC type. + + Parameters + ---------- + obj: or + The object to turn into a Project. + """ + obj.Proxy = self self.setProperties(obj) obj.IfcType = "Project" def setProperties(self, obj): + """Gives the object properties unique to projects. + + Adds the IFC context properties, and the group extension if it does not + already exist. + """ + ArchIFC.IfcContext.setProperties(self, obj) pl = obj.PropertiesList if not hasattr(obj,"Group"): @@ -108,15 +168,35 @@ class _Project(ArchIFC.IfcContext): self.Type = "Project" def onDocumentRestored(self, obj): + """Method run when the document is restored. Re-adds the properties.""" self.setProperties(obj) -class _ViewProviderProject(ArchIFCView.IfcContextView): +class _viewproviderproject(ArchIFCView.IfcContextView): + """A View Provider for the project object.""" def __init__(self,vobj): + """Initialises the project view provider. + + Registers the Proxy as this class object. + + Parameters + ---------- + vobj: + The view provider to turn into a project view provider. + """ + vobj.Proxy = self vobj.addExtension("Gui::ViewProviderGroupExtensionPython", self) def getIcon(self): + """Returns the path to the appropriate icon. + + Returns + ------- + str + Path to the appropriate icon .svg file. + """ + import Arch_rc return ":/icons/Arch_Project_Tree.svg" diff --git a/src/Mod/Arch/ArchWall.py b/src/Mod/Arch/ArchWall.py index 421b1acd37..5844904b8c 100644 --- a/src/Mod/Arch/ArchWall.py +++ b/src/Mod/Arch/ArchWall.py @@ -667,8 +667,10 @@ class _CommandMergeWalls: FreeCAD.ActiveDocument.commitTransaction() class _Wall(ArchComponent.Component): - """The Wall object. Takes a and turns it into a wall, - then uses a to create the wall's shape. + """The Wall object. + + Turns a into a wall object, then uses a to + create the wall's shape. Walls are simple objects, usually vertical, typically obtained by giving a thickness to a base line, then extruding it vertically.