with one click
build-docs
Guide for building documentation and validating docstrings. Use this when asked to build docs, check docstrings, or validate documentation.
Menu
Guide for building documentation and validating docstrings. Use this when asked to build docs, check docstrings, or validate documentation.
| name | build-docs |
| description | Guide for building documentation and validating docstrings. Use this when asked to build docs, check docstrings, or validate documentation. |
This skill covers documentation building and docstring validation workflows for the Semantic Link Labs project.
Use this skill when you need to:
| Component | Details |
|---|---|
| Framework | Sphinx with numpydoc |
| Theme | sphinx_rtd_theme |
| Hosting | ReadTheDocs |
| Source location | docs/source/ |
| Build output | docs/build/html/ |
| Config | docs/source/conf.py |
Install documentation dependencies:
pip install -r docs/requirements.txt
# 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
Open docs/build/html/index.html in a browser.
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
This project uses numpydoc style for all docstrings.
@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
# 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.
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>`_.
"""
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).
"""
Symptom: Sphinx warning about missing docstring.
Fix: Add complete numpydoc-style docstring with all required sections.
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
...
"""
Symptom: Warning about unexpected indentation.
Fix: Use consistent 4-space indentation in docstrings.
Symptom: Warning about broken reference.
Fix: Verify URLs are correct and use proper RST link syntax:
`Link Text <https://example.com>`_
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'
]
cd docs
make html 2>&1 | grep -i warning
cd docs
make clean
make html
# Generate docs for specific module
sphinx-apidoc -f -o source ../src/sempy_labs/admin/
make html
Before committing changes with new or modified functions:
Verify docstring completeness:
Build documentation locally:
cd docs && make html
Check for warnings in build output
Preview the generated HTML to ensure proper rendering
Guide for the visual style, structure, and shared building blocks used by Semantic Link Labs interactive UI tools (HTML widgets and anywidget-based widgets). Use this when adding a new interactive UI, modifying an existing one, or adding shared visual components.
Guide for running code style linters and formatters. Use this when asked to check code style, run linters, or fix formatting issues.
Guide for translating SQL aggregation expressions into DAX measures.
Guide for adding new functions to the library. Use this when implementing new API wrappers or utility functions.
Guide for working with Direct Lake semantic models. Use this when implementing Direct Lake-related features or troubleshooting.
Guide for searching and exploring external GitHub repositories using the gh CLI. Use this when you need reference implementations, patterns, or code examples from open-source projects to help complete your task.