Build Docs

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

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

@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.

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

# 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
    ...
"""

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

# 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

   cd docs && make html