Metadata-Version: 2.4
Name: mdxify
Version: 0.2.13
Summary: Generate MDX API documentation from Python modules
Project-URL: Code, https://github.com/zzstoatzz/mdxify
Author-email: zzstoatzz <thrast36@gmail.com>
License: MIT
Keywords: api,documentation,mdx,python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: griffe>=0.36.0
Description-Content-Type: text/markdown

# mdxify

Generate MDX API documentation from Python modules with automatic navigation structure.

## Installation

```bash
pip install mdxify
```

## Usage

Generate documentation for all modules in a package:

```bash
mdxify --all --root-module mypackage --output-dir docs/python-sdk
```

Generate documentation for specific modules:

```bash
mdxify mypackage.core mypackage.utils --output-dir docs/python-sdk
```

Exclude internal modules from documentation:

```bash
mdxify --all --root-module mypackage --exclude mypackage.internal --exclude mypackage.tests
```

### Options

- `modules`: Specific modules to document
- `--all`: Generate documentation for all modules under the root module
- `--root-module`: Root module to generate docs for (required when using --all)
- `--output-dir`: Output directory for generated MDX files (default: docs/python-sdk)
- `--update-nav/--no-update-nav`: Update docs.json navigation (default: True)
- `--skip-empty-parents`: Skip parent modules that only contain boilerplate (default: False)
- `--anchor-name` / `--navigation-key`: Name of the navigation anchor or group to update (default: 'SDK Reference')
- `--exclude`: Module to exclude from documentation (can be specified multiple times). Excludes the module and all its submodules.

### Navigation Updates

mdxify can automatically update your `docs.json` navigation by finding either anchors or groups:

1. **First run**: Add a placeholder in your `docs.json` using either format:

**Anchor format (e.g., FastMCP):**
```json
{
  "navigation": [
    {
      "anchor": "SDK Reference",
      "pages": [
        {"$mdxify": "generated"}
      ]
    }
  ]
}
```

**Group format (e.g., Prefect):**
```json
{
  "navigation": [
    {
      "group": "SDK Reference",
      "pages": [
        {"$mdxify": "generated"}
      ]
    }
  ]
}
```

2. **Subsequent runs**: mdxify will find and update the existing anchor or group directly - no placeholder needed!

The `--anchor-name` parameter (or its alias `--navigation-key`) identifies which anchor or group to update.

## Features

- **Fast AST-based parsing** - No module imports required
- **MDX output** - Compatible with modern documentation frameworks
- **Automatic navigation** - Generates hierarchical navigation structure
- **Google-style docstrings** - Formats docstrings using Griffe
- **Smart filtering** - Excludes private modules and known test patterns

## Development

```bash
# Install development dependencies
uv sync

# Run tests
uv run pytest

# Run type checking
uv run ty check

# Run linting
uv run ruff check src/ tests/
```