Metadata-Version: 2.4
Name: mkdocs_sharepoint_plugin
Version: 1.2.0
Summary: MkDocs plugin to publish documentation to SharePoint
Author-email: Surj Bains <surjit.bains@gmail.com>
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: pytest==9.0.3
Requires-Dist: pytest-mock==3.12.0
Requires-Dist: coverage==7.5
Requires-Dist: requests
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: pre-commit
Requires-Dist: mkdocs
Requires-Dist: Cython
Requires-Dist: Office365-REST-Python-Client>=2.5.0
Requires-Dist: tenacity>=8.2
Provides-Extra: dev
Requires-Dist: mkdocs; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: black; extra == "dev"

# MkDocs SharePoint Plugin

A MkDocs plugin that automatically publishes your built documentation site to SharePoint Online.

## Features

- **Automatic publishing** - Upload the MkDocs `site_dir` output to SharePoint during `mkdocs build`
- **Folder structure preservation** - Maintains subdirectories when uploading to a document library
- **App-based authentication** - Uses Microsoft Entra app credentials (client ID/secret)
- **Flexible configuration** - Config values with environment variable fallbacks
- **Dry-run mode** - Test your configuration without publishing
- **Debug mode** - Detailed logging for troubleshooting
- **Retry support** - Exponential backoff for transient SharePoint API failures

## Installation

### Install from Source

```shell
pip install .
```

### Development Installation

```shell
pip install -e ".[dev]"
```

### Build from Source

```shell
python -m build
pip install dist/mkdocs_sharepoint_plugin-*.whl
```

## Python Requirements

- **Python:** >=3.7
- **Build System:** setuptools>=61, wheel, build

## Dependencies

### Core Dependencies
- **mkdocs** - The static site generator this plugin extends
- **Office365-REST-Python-Client** - SharePoint REST API client
- **tenacity** - Retry/backoff for API calls
- **requests** - HTTP library
- **pyyaml** - YAML parsing

## Configuration

The plugin is registered as a MkDocs plugin via the entry point:

```
sharepoint = "mkdocs_sharepoint_plugin.plugin:SharePointPlugin"
```

Add the plugin to your `mkdocs.yml`:

```yaml
plugins:
  - sharepoint:
      site_url: https://contoso.sharepoint.com/sites/Team
      tenant_id: your-tenant-id
      documents_folder: /sites/Team/Shared Documents/Docs
      upload_api: graph
      enabled_if_env: MKDOCS_TO_SHAREPOINT
      dryrun: false
      debug: false
```

### Configuration Options

| Option | Description | Default | Required |
|--------|-------------|---------|----------|
| `site_url` | SharePoint site URL | `$SHAREPOINT_SITE_URL` | ✅ |
| `client_id` | Entra app client ID | `$SHAREPOINT_CLIENT_ID` | ✅ |
| `client_secret` | Entra app client secret | `$SHAREPOINT_CLIENT_SECRET` | ✅ |
| `tenant_id` | Entra tenant ID | `$SHAREPOINT_TENANT_ID` / `$AZURE_TENANT_ID` | ✅ for Graph |
| `documents_folder` | Server-relative document library folder | | ✅ |
| `pages_folder` | Server-relative Site Pages folder (for wiki helpers) | `null` | |
| `upload_api` | Upload API: `graph` or `rest` | `graph` | |
| `enabled_if_env` | Environment variable to enable plugin | | |
| `dryrun` | Test mode without publishing | `false` | |
| `debug` | Enable debug logging | `false` | |

## Usage

### Basic Usage

1. Configure the plugin in your `mkdocs.yml`
2. Set up environment variables for SharePoint authentication:
   ```bash
   export SHAREPOINT_SITE_URL=https://contoso.sharepoint.com/sites/Team
   export SHAREPOINT_CLIENT_ID=your-client-id
   export SHAREPOINT_CLIENT_SECRET=your-client-secret
   export SHAREPOINT_TENANT_ID=your-tenant-id
   export MKDOCS_TO_SHAREPOINT=1
   ```
3. Build and publish your documentation:
   ```bash
   mkdocs build
   ```

When `enabled_if_env` is set, the plugin only publishes when the environment variable equals `1`.

### Dry Run

Set `dryrun: true` in your plugin config to log what would be uploaded without calling the SharePoint API.

## SharePoint API Helpers

The repo also includes helper functions and an optional CLI for direct SharePoint publishing outside MkDocs:

- Module: `src/mkdocs_sharepoint_plugin/sharepoint_publish.py`
- CLI: `tools/sharepoint_publish.py`

Example CLI usage:

```shell
python tools/sharepoint_publish.py upload-docs \
    --local-dir site \
    --server-folder "/sites/your-site/Shared Documents/Docs" \
    --upload-api graph

python tools/sharepoint_publish.py create-wiki \
    --title "How do I reset my password?" \
    --html-file page.html \
    --pages-folder "/sites/your-site/SitePages"
```

## Development

### Run Tests

```shell
coverage run -m pytest
coverage report
```

### Format Code

```shell
black src tests
```

## Authentication Notes

SharePoint Online automation typically uses app-only authentication in Microsoft Entra ID. The app needs appropriate SharePoint permissions (for example `Sites.ReadWrite.All`) and admin consent for the tenant.

Store secrets in environment variables or a secrets manager. Do not commit credentials to source control.

## Related Projects

- [python-mkdocs-to-confluence](https://github.com/polarpoint-io/python-mkdocs-to-confluence) - Sister plugin for publishing MkDocs documentation to Confluence

## Docker Image

Releases publish a versioned container image to GitHub Container Registry via [`@codedependant/semantic-release-docker`](https://www.npmjs.com/package/@codedependant/semantic-release-docker):

```
ghcr.io/polarpoint-io/python-mkdocs-to-sharepoint:<version>
```

Example usage:

```shell
docker run --rm -v "$PWD:/docs" -w /docs \
  ghcr.io/polarpoint-io/python-mkdocs-to-sharepoint:latest build
```

Tags follow semantic versioning (`latest`, `1.2.3`, `1-latest`, `1.2`).
