Documenting Custom FreeCAD Python Workbenches

Documenting a custom FreeCAD Python workbench ensures that end users and contributors can easily install, navigate, and utilize your tools. This guide outlines the essential layers of workbench documentation, including in-app command tooltips, structured repository files, context-sensitive help integration, and community wiki publishing, giving you a straightforward framework to support your project.

1. In-App UI Documentation and Tooltips

The first point of contact for users is inside FreeCAD itself. Every Python command in your workbench should provide clear interface feedback using the GetResources method.

When defining your command class, specify descriptive text fields:

class CustomCommand:
    def GetResources(self):
        return {
            "Pixmap": "path/to/icon.svg",
            "MenuText": "Run Custom Tool",
            "ToolTip": "Short one-sentence explanation of what the tool does.",
            "WhatsThis": "Detailed explanation of inputs, expected selections, and outputs.",
            "StatusTip": "Displays brief instructions in the FreeCAD status bar.",
        }
  • ToolTip: Keep it under 10 words. Focus on the direct action (e.g., "Generates a parametric bracket from a selected face").
  • WhatsThis: Use this to explain required prerequisites, such as specific geometry selections or required document states.

2. The Repository README

For users installing via Git or the FreeCAD Addon Manager, the README.md in your root repository is the primary reference. Structure your README with the following sections:

  • Overview: A concise summary of the workbench's purpose and primary use cases.
  • Prerequisites: Dependencies such as external Python libraries (e.g., NumPy, SciPy) and minimum compatible FreeCAD versions (e.g., FreeCAD 0.21 or 1.0+).
  • Installation: Instructions for installing through the native Addon Manager (Tools > Addon manager) as well as manual installation via the Mod/ directory.
  • Workflow Guide: Step-by-step instructions for core operations, accompanied by explicit input/output expectations.
  • Reporting Issues: Direct links to your bug tracker and instructions on what information to provide (e.g., OS, FreeCAD version info from Help > About FreeCAD).

3. Native Help System Integration

FreeCAD includes an internal help system accessible when users press F1 or click contextual help icons. You can hook your workbench commands directly into this system.

Associate your commands with external documentation URLs or local HTML files by directing the WhatsThis attribute to open your documentation:

import FreeCADGui
import webbrowser


class HelpCommand:
    def Activated(self):
        webbrowser.open("https://your-documentation-url.org")

    def GetResources(self):
        return {
            "Pixmap": "help_icon.svg",
            "MenuText": "Workbench Documentation",
            "ToolTip": "Opens online documentation in your web browser",
        }

For offline documentation, bundle a doc/ directory containing static HTML files within your workbench package and resolve the relative file path using Python's os.path module to load it into FreeCAD's built-in web browser:

import os
import FreeCADGui

doc_path = os.path.join(
    os.path.dirname(__file__), "doc", "index.html"
)
FreeCADGui.getMainWindow().findChild(QtGui.QAction, "Std_OnlineHelp").trigger()

4. FreeCAD Community Wiki Pages

If your workbench is distributed through the official Addon Manager, creating pages on the official FreeCAD Wiki helps standardize your tool for the broader community.

Follow the standard FreeCAD Wiki page structure:

  • Header: Workbench metadata, including author, version, and repository URL.
  • Description: Detailed explanation of the concepts behind the workbench.
  • Tool List: Dedicated sub-sections for each tool featuring the tool icon, menu path, keyboard shortcut, and step-by-step execution procedure.
  • Scripting / API: Code snippets showing how to invoke workbench functions headlessly via the Python console.

5. Code-Level and API Documentation

For power users and macro writers, document the underlying Python modules using standard docstrings (PEP 257). Use Google or NumPy docstring format:

def make_custom_feature(base_object, thickness=2.0):
    """Creates a custom parametric feature from an existing Part object.

    Args:
        base_object (Part.Feature): The parent object to bind the feature to.
        thickness (float, optional): Wall thickness in millimeters. Defaults to 2.0.

    Returns:
        App.DocumentObject: The created FeaturePython object.
    """
    pass

Automating API documentation via tools like Sphinx or MkDocs allows you to publish developer references directly to GitHub Pages or Read the Docs, providing complete coverage for users extending your code.