build-docs | SkillBundle

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:

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

View Built Documentation

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

ReadTheDocs Configuration

The project uses .readthedocs.yaml for automated builds:

Docstring Standards

Docstring Style

This project uses numpydoc style for all docstrings.

Required Sections

Short description — One-line summary of what the function does
Extended description — Detailed explanation (optional but recommended)
Parameters — Document each parameter with type and description
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

Parameter Documentation Patterns

Standard Parameter Formats

API Reference Links

Always include links to API documentation:

Service Principal Note

For functions supporting Service Principal authentication:

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.

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:

Sphinx Configuration

Key settings in docs/source/conf.py:

Validating Documentation

Check for Warnings

Clean Build

Verify Specific Module

Pre-Commit Documentation Check

Before committing changes with new or modified functions:

Verify docstring completeness:
- Short description present
- All parameters documented with types
- Return value documented
- API reference link included (if applicable)
Build documentation locally:
```
cd docs && make html
```
Check for warnings in build output
Preview the generated HTML to ensure proper rendering

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:

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

View Built Documentation

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

ReadTheDocs Configuration

The project uses .readthedocs.yaml for automated builds:

Docstring Standards

Docstring Style

This project uses numpydoc style for all docstrings.

Required Sections

Short description — One-line summary of what the function does
Extended description — Detailed explanation (optional but recommended)
Parameters — Document each parameter with type and description
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

Parameter Documentation Patterns

Standard Parameter Formats

API Reference Links

Always include links to API documentation:

Service Principal Note

For functions supporting Service Principal authentication:

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.

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:

Sphinx Configuration

Key settings in docs/source/conf.py:

Validating Documentation

Check for Warnings

Clean Build

Verify Specific Module

Pre-Commit Documentation Check

Before committing changes with new or modified functions:

Verify docstring completeness:
- Short description present
- All parameters documented with types
- Return value documented
- API reference link included (if applicable)
Build documentation locally:
```
cd docs && make html
```
Check for warnings in build output
Preview the generated HTML to ensure proper rendering