--- name: build-docs description: Guide for building documentation and validating docstrings. Use this when asked to build docs, check docstrings, or validate documentation. --- # 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 | 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` | --- ## Building Documentation Locally ### Prerequisites Install documentation dependencies: ```bash pip install -r docs/requirements.txt ``` ### Build Commands ```bash # 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: ```yaml 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 ```python @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 `_. Service Principal Authentication is supported (see `here `_ 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 `_. 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 ```python # 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: ```python """ This is a wrapper function for the following API: `Items - List Items `_. """ ``` ### Service Principal Note For functions supporting Service Principal authentication: ```python """ Service Principal Authentication is supported (see `here `_ 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. ```python # 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: ```python `Link Text `_ ``` --- ## Sphinx Configuration Key settings in `docs/source/conf.py`: ```python # 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', 'powerbiclient' ] ``` --- ## Validating Documentation ### Check for Warnings ```bash cd docs make html 2>&1 | grep -i warning ``` ### Clean Build ```bash cd docs make clean make html ``` ### Verify Specific Module ```bash # 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**: ```bash cd docs && make html ``` 3. **Check for warnings** in build output 4. **Preview the generated HTML** to ensure proper rendering