BIM workbench is not fully documented

[furgo16]

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

• BIM: BIM_Sketch is not documented #14085
• BIM: Arch_Level is not documented #14086
• BIM: Separator is not documented
• BIM: BIM_Column is not documented
• BIM: BIM_Beam is not documented
• BIM: BIM_Slab is not documented
• BIM: BIM_Door is not documented
• BIM: BIM_GenericTools is not documented
• BIM: BIM_Text is not documented
• BIM: BIM_DimensionAligned is not documented
• BIM: BIM_DimensionHorizontal is not documented
• BIM: BIM_DimensionVertical is not documented
• BIM: BIM_Leader is not documented
• BIM: BIM_TDPage is not documented
• BIM: BIM_TDView is not documented
• BIM: BIM_Shape2DView is not documented
• BIM: BIM_Clone is not documented
• BIM: BIM_Unclone is not documented
• BIM: BIM_Ofset2D is not documented
• BIM: BIM_Rewire is not documented
• BIM: BIM_Glue is not documented
• BIM: BIM_Reextrude is not documented
• BIM: BIM_Extrude is not documented
• BIM: BIM_Reextrude is not documented
• BIM: BIM_Cut is not documented
• BIM: BIM_Fuse is not documented
• BIM: BIM_Common is not documented
• BIM: BIM_Compound is not documented
• BIM: BIM_SimpleCopy is not documented
• BIM: BIM_ProjectManager is not documented
• BIM: BIM_Material is not documented

Overview: documentation status

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

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]

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

[Roy-043]

Please stop creating related issues.

[yorikvanhavre]

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]

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

[Roy-043]

but why not?

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

[yorikvanhavre]

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]

@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]

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]

@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]

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]

Documentation has a lot of those quirks 😅 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