build-docs

Building and Validating Documentation

This skill covers documentation building and docstring validation workflows for the Semantic Link Labs project.

When to Use This Skill

Use this skill when you need to:

• Build documentation locally
• Validate docstrings are properly formatted
• Check for documentation warnings or errors
• Ensure new functions have proper documentation
• Preview documentation before pushing

Documentation Framework

Building Documentation Locally

Prerequisites

Install documentation dependencies:

pip install -r docs/requirements.txt

Build Commands

# Navigate to docs directory
cd docs

# Generate API documentation from source code
sphinx-apidoc -f -o source ../src/sempy_labs/

# Build HTML documentation
make html

# Or on Windows
make.bat html

View Built Documentation

Open docs/build/html/index.html in a browser.

ReadTheDocs Configuration

The project uses .readthedocs.yaml for automated builds:

version: 2
build:
  os: ubuntu-22.04
  tools:
    python: "3.12"
  jobs:
    pre_build:
      - sphinx-apidoc -f -o docs/source src/sempy_labs/
sphinx:
  configuration: docs/source/conf.py
python:
   install:
   - requirements: docs/requirements.txt

Docstring Standards

Docstring Style

This project uses numpydoc style for all docstrings.

Required Sections

1. Short description — One-line summary of what the function does
2. Extended description — Detailed explanation (optional but recommended)
3. Parameters — Document each parameter with type and description
4. Returns — Document return value(s)

Optional Sections

• Raises — Document exceptions that may be raised
• Examples — Provide usage examples
• Notes — Additional context or implementation details
• See Also — Related functions

Example Docstring

@log
def list_workspaces(
    capacity: Optional[str | UUID] = None,
    workspace_state: Optional[str] = None,
) -> pd.DataFrame:
    """
    Lists workspaces for the organization.

    This is a wrapper function for the following API: `Workspaces - List Workspaces <https://learn.microsoft.com/rest/api/fabric/admin/workspaces/list-workspaces>`_.

    Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).

    Parameters
    ----------
    capacity : str | uuid.UUID, default=None
        Returns only the workspaces in the specified Capacity.
    workspace_state : str, default=None
        Return only the workspace with the requested state.
        You can find the possible states in `Workspace States <https://learn.microsoft.com/rest/api/fabric/admin/workspaces/list-workspaces?tabs=HTTP#workspacestate>`_.

    Returns
    -------
    pandas.DataFrame
        A pandas dataframe showing a list of workspaces for the organization.
        Columns include: 'Id', 'Name', 'State', 'Type', 'Capacity Id'.

    Raises
    ------
    FabricHTTPException
        If the API request fails.

    Examples
    --------
    >>> import sempy_labs as labs
    >>> df = labs.list_workspaces()
    >>> df = labs.list_workspaces(capacity="My Capacity")
    """
    pass

Parameter Documentation Patterns

Standard Parameter Formats

# Simple parameter
item_type : str
    The type of item to filter by.

# Parameter with default
item_type : str, default=None
    The type of item to filter by. If None, returns all types.

# Union type parameter
workspace : str | uuid.UUID, default=None
    The Fabric workspace name or ID.
    Defaults to None which resolves to the workspace of the attached lakehouse
    or if no lakehouse attached, resolves to the workspace of the notebook.

# Boolean parameter
readonly : bool, default=True
    If True, opens in read-only mode. If False, allows modifications.

# List parameter
columns : List[str], default=None
    A list of column names to include. If None, includes all columns.

API Reference Links

Always include links to API documentation:

"""
This is a wrapper function for the following API: `Items - List Items <https://learn.microsoft.com/rest/api/fabric/core/items/list-items>`_.
"""

Service Principal Note

For functions supporting Service Principal authentication:

"""
Service Principal Authentication is supported (see `here <https://github.com/microsoft/semantic-link-labs/blob/main/notebooks/Service%20Principal.ipynb>`_ for examples).
"""

Common Documentation Issues

Missing or Incomplete Docstrings

Symptom: Sphinx warning about missing docstring.

Fix: Add complete numpydoc-style docstring with all required sections.

Type Annotation Mismatches

Symptom: Warning about type mismatch between signature and docstring.

Fix: Ensure docstring parameter types match function signature type hints.

# Function signature
def my_func(workspace: Optional[str | UUID] = None) -> pd.DataFrame:

# Docstring should match
"""
Parameters
----------
workspace : str | uuid.UUID, default=None
    ...

Returns
-------
pandas.DataFrame
    ...
"""

Indentation Errors

Symptom: Warning about unexpected indentation.

Fix: Use consistent 4-space indentation in docstrings.

Broken Links

Symptom: Warning about broken reference.

Fix: Verify URLs are correct and use proper RST link syntax:

`Link Text <https://example.com>`_

Sphinx Configuration

Key settings in docs/source/conf.py:

# Extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.intersphinx',
]

# Napoleon settings for numpydoc
napoleon_numpy_docstring = True

# Mock imports for packages not available during build
autodoc_mock_imports = [
    'delta', 'synapse', 'jwt', 'semantic-link-sempy',
    'pyspark', 'anywidget', 'sqlglot'
]

Validating Documentation

Check for Warnings

cd docs
make html 2>&1 | grep -i warning

Clean Build

cd docs
make clean
make html

Verify Specific Module

# Generate docs for specific module
sphinx-apidoc -f -o source ../src/sempy_labs/admin/
make html

Pre-Commit Documentation Check

Before committing changes with new or modified functions:

1. Verify docstring completeness:

   • Short description present
   • All parameters documented with types
   • Return value documented
   • API reference link included (if applicable)

2. Build documentation locally:

   cd docs && make html
   

3. Check for warnings in build output

4. Preview the generated HTML to ensure proper rendering