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

pip install sphinx-mintlify

Usage

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

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:

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:

cp -r docs/api/* docs/

Example Output

For a class like this:

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:

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

The password to verify

Returns

True if authentication successful, False otherwise

Raises

• ValueError: If password is empty

Example

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.