Metadata-Version: 2.4
Name: sphinx-mintlify
Version: 0.1.1
Summary: Sphinx extension for generating Mintlify-compatible MDX documentation
Project-URL: Homepage, https://github.com/nottelabs/sphinx_mintlify
Project-URL: Repository, https://github.com/nottelabs/sphinx_mintlify
Author-email: Notte Labs <hello@notte.cc>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Sphinx
Classifier: Framework :: Sphinx :: Extension
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: docutils>=0.17.0
Requires-Dist: sphinx>=4.0.0
Requires-Dist: typing-extensions>=4.0.0
Description-Content-Type: text/markdown

# Sphinx Mintlify Extension

A Sphinx extension that generates Mintlify-compatible MDX documentation from Python docstrings, creating organized documentation with a folder per class and a file per method.

## Features

- Generates Mintlify-compatible MDX documentation
- Creates a folder per class with individual method documentation
- Supports class inheritance documentation
- Preserves type hints and parameter descriptions
- Supports async methods and properties
- Generates proper frontmatter
- Customizable templates and metadata
- Method grouping and ordering options

## Installation

```bash
pip install sphinx-mintlify
```

## Usage

1. Add the extension to your Sphinx project's `conf.py`:

```python
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode',
    'sphinx.ext.napoleon',
    'sphinx_mintlify',
]

# Configure the extension
classmd_output_dir = 'docs/api'  # Output directory for generated MDX files

# List classes to document
classmd_classes = [
    'myproject.models.User',
    {
        'path': 'myproject.utils.Helper',
        'name': 'HelperClass'
    }
]

# Optional: Configure method documentation
classmd_method_options = {
    'include_source': True,
    'include_examples': True,
    'group_by_type': True
}

# Optional: Configure method ordering
classmd_method_order = [
    '__init__',
    'public_methods',
    'private_methods',
    'static_methods',
    'class_methods'
]

# Optional: Custom templates
classmd_templates = {
    'class_index': '_templates/class_index.mdx',
    'method': '_templates/method.mdx'
}

# Optional: Additional metadata
classmd_metadata = {
    'api_version': '1.0.0',
    'api_status': 'stable',
    'sidebar_label': 'API Reference',
    'sidebar_position': 2
}
```

2. Run Sphinx to generate the documentation:

```bash
sphinx-build -b dirhtml source/ _build/dirhtml
```

The extension will automatically create a folder structure in your `classmd_output_dir` like this:

```
docs/api/
├── User/
│   ├── index.mdx
│   ├── __init__.mdx
│   ├── authenticate.mdx
│   └── update_profile.mdx
└── HelperClass/
    ├── index.mdx
    ├── utility_method1.mdx
    └── utility_method2.mdx
```

3. Copy the generated MDX files to your Mintlify documentation folder:

```bash
cp -r docs/api/* docs/
```

## Example Output

For a class like this:

```python
class User:
    def authenticate(self, password: str) -> bool:
        """Authenticate the user with the given password.
        
        Args:
            password: The password to verify
            
        Returns:
            bool: True if authentication successful, False otherwise
            
        Raises:
            ValueError: If password is empty
        """
        pass
```

The extension will generate an MDX file (`authenticate.mdx`) like this:

```mdx
---
title: "User.authenticate"
description: "Authenticate the user with the given password"
---

# authenticate

Authenticate the user with the given password.

## Signature

```python
def authenticate(self, password: str) -> bool
```

## Parameters

<ParamField path="password" type="str">
  The password to verify
</ParamField>

## Returns

<ResponseField type="bool">
  True if authentication successful, False otherwise
</ResponseField>

## Raises

- `ValueError`: If password is empty

## Example

```python
user = User()
is_authenticated = user.authenticate("my_password")
```
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License. 