search

FreeCAD / FreeCAD

This is the official source code of FreeCAD, a free and opensource multiplatform 3D parametric modeler.
https://www.freecad.org
Other
18.2k stars 3.86k forks source link

BIM workbench is not fully documented #14084

Open furgo16 opened 1 month ago

furgo16 commented 1 month ago

Problem description

Now that the Arch workbench is becoming the BIM workbench, there are a number of additional commands in the later that need to be documented.

This issue collects an overview and a list of tasks to organize the documentation effort.

Documentation tasks

Overview: documentation status

Toolbar Command Documented Notes
Drafting tools BIM_Sketch :x:
Drafting tools Draft_Line :white_check_mark:
Drafting tools Draft_Wire :white_check_mark:
Drafting tools Draft_Circle :white_check_mark:
Drafting tools Draft_Arc :white_check_mark:
Drafting tools Draft_Arc_3Points :white_check_mark:
Drafting tools Draft_Fillet :white_check_mark:
Drafting tools Draft_Ellipse :white_check_mark:
Drafting tools Draft_Polygon :white_check_mark:
Drafting tools Draft_Rectangle :white_check_mark:
Drafting tools Draft_BSpline :white_check_mark:
Drafting tools Draft_BezCurve :white_check_mark:
Drafting tools Draft_CubicBezCurve :white_check_mark:
Drafting tools Draft_Point :white_check_mark:
Draft snap Draft_Snap_Lock :white_check_mark:
Draft snap Draft_Snap_Endpoint :white_check_mark:
Draft snap Draft_Snap_Midpoint :white_check_mark:
Draft snap Draft_Snap_Center :white_check_mark:
Draft snap Draft_Snap_Angle :white_check_mark:
Draft snap Draft_Snap_Intersection :white_check_mark:
Draft snap Draft_Snap_Perpendicular :white_check_mark:
Draft snap Draft_Snap_Extension :white_check_mark:
Draft snap Draft_Snap_Parallel :white_check_mark:
Draft snap Draft_Snap_Special :white_check_mark:
Draft snap Draft_Snap_Near :white_check_mark:
Draft snap Draft_Snap_Ortho :white_check_mark:
Draft snap Draft_Snap_Grid :white_check_mark:
Draft snap Draft_Snap_WorkingPlane :white_check_mark:
Draft snap Draft_Snap_Dimensions :white_check_mark:
Draft snap Draft_ToggleGrid :white_check_mark:
3D/BIM tools BIM_Project :white_check_mark:
3D/BIM tools Arch_Site :white_check_mark:
3D/BIM tools Arch_Building :white_check_mark:
3D/BIM tools Arch_Level :x:
3D/BIM tools Arch_Space :white_check_mark:
3D/BIM tools Separator :x:
3D/BIM tools Arch_Wall :white_check_mark:
3D/BIM tools Arch_CurtainWall :white_check_mark:
3D/BIM tools BIM_Column :x:
3D/BIM tools BIM_Beam :x:
3D/BIM tools BIM_Slab :x:
3D/BIM tools BIM_Door :x:
3D/BIM tools Arch_Window :white_check_mark:
3D/BIM tools Arch_Pipe :white_check_mark:
3D/BIM tools Arch_PipeConnector :white_check_mark:
3D/BIM tools Arch_Stairs :white_check_mark:
3D/BIM tools Arch_Roof :white_check_mark:
3D/BIM tools Arch_Panel :white_check_mark:
3D/BIM tools Arch_Frame :white_check_mark:
3D/BIM tools Arch_Fence :white_check_mark:
3D/BIM tools Arch_Truss :white_check_mark:
3D/BIM tools Arch_Rebar :white_check_mark:
3D/BIM tools BIM_GenericTools :x:
Annotation tools BIM_Text :x:
Annotation tools Draft_ShapeString :white_check_mark:
Annotation tools BIM_DimensionAligned :x:
Annotation tools BIM_DimensionHorizontal :x:
Annotation tools BIM_DimensionVertical :x:
Annotation tools BIM_Leader :x:
Annotation tools Draft_Label :white_check_mark:
Annotation tools Arch_Axis :white_check_mark:
Annotation tools Arch_AxisSystem :white_check_mark:
Annotation tools Arch_Grid :white_check_mark:
Annotation tools Arch_SectionPlane :white_check_mark:
Annotation tools Draft_Hatch :white_check_mark:
Annotation tools BIM_TDPage :x:
Annotation tools BIM_TDView :x:
Annotation tools BIM_Shape2DView :x:
Modification tools Draft_Move :white_check_mark:
Modification tools BIM_Copy :white_check_mark:
Modification tools Draft_Rotate :white_check_mark:
Modification tools BIM_Clone :white_check_mark:
Modification tools BIM_Unclone :x:
Modification tools Draft_Offset :white_check_mark:
Modification tools BIM_Offset2D :x:
Modification tools Draft_Trimex :white_check_mark:
Modification tools Draft_Join :white_check_mark:
Modification tools Draft_Split :white_check_mark:
Modification tools Draft_Scale :white_check_mark:
Modification tools Draft_Stretch :white_check_mark:
Modification tools BIM_Rewire :x:
Modification tools BIM_Glue :x:
Modification tools Draft_Upgrade :white_check_mark:
Modification tools Draft_Downgrade :white_check_mark:
Modification tools Draft_Draft2Sketch :white_check_mark:
Modification tools Arch_CutPlane :white_check_mark:
Modification tools Arch_Add :white_check_mark:
Modification tools Arch_Remove :white_check_mark:
Modification tools BIM_Reextrude :x:
Modification tools Draft_OrthoArray :white_check_mark:
Modification tools Draft_PathArray :white_check_mark:
Modification tools Draft_PointArray :white_check_mark:
Modification tools Draft_Mirror :white_check_mark:
Modification tools BIM_Extrude :x:
Modification tools BIM_Cut :x:
Modification tools BIM_Fuse :x:
Modification tools BIM_Common :x:
Modification tools BIM_Compound :x:
Modification tools BIM_SimpleCopy :x:
Manage tools BIM_Setup :white_check_mark:
Manage tools BIM_Views :white_check_mark:
Manage tools BIM_ProjectManager :x:
Manage tools BIM_Windows :white_check_mark:
Manage tools BIM_IfcElements :white_check_mark:
Manage tools BIM_IfcQuantities :white_check_mark:
Manage tools BIM_IfcProperties :white_check_mark:
Manage tools BIM_Classification :white_check_mark:
Manage tools BIM_Layers :white_check_mark:
Manage tools BIM_Material :x:
Manage tools Arch_Schedule :white_check_mark:
Manage tools BIM_Preflight :white_check_mark:
Manage tools Draft_AnnotationStyleEditor :white_check_mark:

Full version info

OS: Ubuntu Core 22 (ubuntu:GNOME/ubuntu)
Word size of FreeCAD: 64-bit
Version: 0.22.0dev.37330 (Git) Snap 1022
Build type: Release
Branch: main
Hash: a094bf0df7e2b3e5c5b2e3b158a9040a6474892f
Python 3.10.12, Qt 5.15.10, Coin 4.0.0, Vtk 7.1.1, OCC 7.7.1
Installed mods: 
  * OpenTheme 2024.5.16
  * Curves 0.6.36
  * ezydxf
  * ExplodedAssembly
  * BillOfMaterials 0.0.8.2
  * Ondsel-Lens 2024.5.6.01

Subproject(s) affected?

Arch

Anything else?

The overview table can be regenerated running this code on the Python console, with the BIM workbench active. Improvements welcome:

import requests
common_toolbars = ['File', 'Edit', 'Clipboard', 'Workbench', 'Macro', 'View', 'Individual views', 'Structure', 'Help']
freecad_docs_url = "https://wiki.freecad.org"
header = "| Toolbar | Command | Documented | Notes |\n| --- | --- | --- | --- |"
header_printed = False
workbench = Gui.activeWorkbench()
toolbar_items = workbench.getToolbarItems()
for toolbar in toolbar_items:
    for command in toolbar_items[toolbar]:
        if toolbar not in common_toolbars:
            if not header_printed:
                print(header)
                header_printed = True
            response = requests.head(f"{freecad_docs_url}/{command}")
            if response.status_code == 200:
                is_documented = True
            elif 400 <= response.status_code < 500:
                is_documented = False
            else:
                is_documented = None
            is_documented = ':white_check_mark:' if is_documented else ':x:'
            print("|", toolbar, "|", f"[{command}]({freecad_docs_url}/{command})", "|", is_documented, "|", " ", "|")
Roy-043 commented 1 month ago

It is new to me that we use GitHub to track the documentation effort. When was that decided??

Roy-043 commented 1 month ago

Please stop creating related issues.

yorikvanhavre commented 1 month ago

It is new to me that we use GitHub to track the documentation effort. When was that decided??

I don't think it was, but why not? I don't see well where else it could be tracked efficiently, and it might be a good thing so we try to have the doc in shape for 1.0.

The day the doc is in its own repo, of course, that will be better, that's where we'll track things...

But this should be discussed somewhere

maxwxyz commented 1 month ago

@furgo16 could you please use this issue for tracking documentation? I've noticed you started creating issues for every command.

Roy-043 commented 1 month ago

but why not?

I can think of several reasons. But we should not have that discussion here.

yorikvanhavre commented 1 month ago

I can think of several reasons. But we should not have that discussion here.

Agreed. Let's bring the topic up during next M3 meeting maybe

yorikvanhavre commented 1 month ago

@furgo16 nice script BTW! Maybe something like that could also be used to regenerate the tools table at https://wiki.freecad.org/BIM_Workbench

furgo16 commented 1 month ago

I filed this issue with the spirit of contributing. The intention was to serve as the central point to organize the effort (similar to a GitLab epic) , with an issue task list and issues for every command, to more easily track the status. But also importantly to encourage other contributors to pick a task and complete the BIM documentation collaboratively. Those separate issues could also be managed in projects, similarly to what was done with the TNP effort.

Regardless of the platform, I personally can only see advantages in using the same tools to manage documentation as code, especially if there is eventually a migration to markdown files for docs. Yet others might see this differently, which is absolutely fine. Constructive debate is one of the great things about open source.

I was not anticipating filing this issue could stir negative feelings. Apologies for that, as it was not my intention. Feel free to close it if not desired. No hard feelings, happy to keep contributing in another area of the project if that's useful. Thanks.

furgo16 commented 1 month ago

@furgo16 nice script BTW! Maybe something like that could also be used to regenerate the tools table at https://wiki.freecad.org/BIM_Workbench

Thanks, I had thought about that as well! I would have liked to add each command's icon to the table. In the end, I could not figure out a way to retrieve the icons (and to upload them without manual steps), so I kept it simple as it is.

krushia commented 1 month ago

A few notes from a clueless BIM user

  1. I got a good laugh when seeing the "first run" dialog for BIM today, which has a link to "complete documentation" (sorry didn't get a screenshot). Clicking the link opens https://wiki.freecad.org/BIM_Workbench where the first words read "This documentation is not finished." I don't have the heart to open a bug just for that nitpick :)
  2. Whatever happened to the GSoC documentation overhaul project from last year? From what I've read, it was supposed to be the path forward.
yorikvanhavre commented 1 month ago

Documentation has a lot of those quirks :sweat_smile: Hopefully very soon we'll remove that "documentation is in process" note :) The welcome screen also needs a rework anyway.

Regarding last year's GSoC project, it basically still lacks functionality and didn't reach yet all the goals we wanted, so it's kind of stalled currently, and we are still using the wiki for now. But indeed after the release we need to retake that effort

Roy-043 commented 2 weeks ago

FYI: The BIM Wiki documentation has been provisionally updated. See BIM Workbench. Missing pages appear in red. Note that 7 tools in the Modify menu are wrappers for Part tools. Perhaps they can be removed and the Part tools used directly (same as has been done with Part Builder)?

yorikvanhavre commented 4 days ago

Excellent! I'll give it a push this week too.

Regarding the "wrapped" Part tools, the original idea was to be able to late-load the Part WB so BIM starts fast. Not sure how relevant that is...