| Name | mdxify JSON |
| Version |
0.2.31
JSON |
| download |
| home_page | None |
| Summary | Generate MDX API documentation from Python modules |
| upload_time | 2025-08-31 14:21:30 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
api
documentation
mdx
python
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# mdxify
Generate MDX API documentation from Python modules with automatic navigation structure.
## Projects Using mdxify
mdxify is powering the API documentation for the following projects:
- **[FastMCP](https://github.com/jlowin/fastmcp)** by Jeremiah Lowin - See it in action at [gofastmcp.com](https://gofastmcp.com/python-sdk)
- **[Prefect](https://github.com/PrefectHQ/prefect)** - See the API reference at [docs.prefect.io](https://docs.prefect.io/v3/api-ref/python)
## 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.
- `--repo-url`: GitHub repository URL for source code links (e.g., https://github.com/owner/repo). If not provided, will attempt to detect from git remote.
- `--branch`: Git branch name for source code links (default: main)
### 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.
### Source Code Links
mdxify can automatically add links to source code on GitHub for all functions, classes, and methods:
```bash
# Auto-detect repository from git remote
mdxify --all --root-module mypackage
# Or specify repository explicitly
mdxify --all --root-module mypackage --repo-url https://github.com/owner/repo --branch develop
```
This adds source links next to each function/class/method that link directly to the code on GitHub.
#### Customizing Source Link Text
You can customize the link text/symbol using the `MDXIFY_SOURCE_LINK_TEXT` environment variable:
```bash
# Use custom text
export MDXIFY_SOURCE_LINK_TEXT="[src]"
mdxify --all --root-module mypackage
# Use emoji
export MDXIFY_SOURCE_LINK_TEXT="🔗"
mdxify --all --root-module mypackage
# Use different Unicode symbol (default is "view on GitHub ↗")
export MDXIFY_SOURCE_LINK_TEXT="⧉"
mdxify --all --root-module mypackage
```
## 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/
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mdxify",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "api, documentation, mdx, python",
"author": null,
"author_email": "zzstoatzz <thrast36@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/10/5d/d53a0a406ce87183706c920f15fab45e1e6ebf15e4efc9ba2f1b1de27e3a/mdxify-0.2.31.tar.gz",
"platform": null,
"description": "# mdxify\n\nGenerate MDX API documentation from Python modules with automatic navigation structure.\n\n## Projects Using mdxify\n\nmdxify is powering the API documentation for the following projects:\n\n- **[FastMCP](https://github.com/jlowin/fastmcp)** by Jeremiah Lowin - See it in action at [gofastmcp.com](https://gofastmcp.com/python-sdk)\n- **[Prefect](https://github.com/PrefectHQ/prefect)** - See the API reference at [docs.prefect.io](https://docs.prefect.io/v3/api-ref/python)\n\n## Installation\n\n```bash\npip install mdxify\n```\n\n## Usage\n\nGenerate documentation for all modules in a package:\n\n```bash\nmdxify --all --root-module mypackage --output-dir docs/python-sdk\n```\n\nGenerate documentation for specific modules:\n\n```bash\nmdxify mypackage.core mypackage.utils --output-dir docs/python-sdk\n```\n\nExclude internal modules from documentation:\n\n```bash\nmdxify --all --root-module mypackage --exclude mypackage.internal --exclude mypackage.tests\n```\n\n### Options\n\n- `modules`: Specific modules to document\n- `--all`: Generate documentation for all modules under the root module\n- `--root-module`: Root module to generate docs for (required when using --all)\n- `--output-dir`: Output directory for generated MDX files (default: docs/python-sdk)\n- `--update-nav/--no-update-nav`: Update docs.json navigation (default: True)\n- `--skip-empty-parents`: Skip parent modules that only contain boilerplate (default: False)\n- `--anchor-name` / `--navigation-key`: Name of the navigation anchor or group to update (default: 'SDK Reference')\n- `--exclude`: Module to exclude from documentation (can be specified multiple times). Excludes the module and all its submodules.\n- `--repo-url`: GitHub repository URL for source code links (e.g., https://github.com/owner/repo). If not provided, will attempt to detect from git remote.\n- `--branch`: Git branch name for source code links (default: main)\n\n### Navigation Updates\n\nmdxify can automatically update your `docs.json` navigation by finding either anchors or groups:\n\n1. **First run**: Add a placeholder in your `docs.json` using either format:\n\n**Anchor format (e.g., FastMCP):**\n```json\n{\n \"navigation\": [\n {\n \"anchor\": \"SDK Reference\",\n \"pages\": [\n {\"$mdxify\": \"generated\"}\n ]\n }\n ]\n}\n```\n\n**Group format (e.g., Prefect):**\n```json\n{\n \"navigation\": [\n {\n \"group\": \"SDK Reference\",\n \"pages\": [\n {\"$mdxify\": \"generated\"}\n ]\n }\n ]\n}\n```\n\n2. **Subsequent runs**: mdxify will find and update the existing anchor or group directly - no placeholder needed!\n\nThe `--anchor-name` parameter (or its alias `--navigation-key`) identifies which anchor or group to update.\n\n### Source Code Links\n\nmdxify can automatically add links to source code on GitHub for all functions, classes, and methods:\n\n```bash\n# Auto-detect repository from git remote\nmdxify --all --root-module mypackage\n\n# Or specify repository explicitly\nmdxify --all --root-module mypackage --repo-url https://github.com/owner/repo --branch develop\n```\n\nThis adds source links next to each function/class/method that link directly to the code on GitHub.\n\n#### Customizing Source Link Text\n\nYou can customize the link text/symbol using the `MDXIFY_SOURCE_LINK_TEXT` environment variable:\n\n```bash\n# Use custom text\nexport MDXIFY_SOURCE_LINK_TEXT=\"[src]\"\nmdxify --all --root-module mypackage\n\n# Use emoji\nexport MDXIFY_SOURCE_LINK_TEXT=\"\ud83d\udd17\"\nmdxify --all --root-module mypackage\n\n# Use different Unicode symbol (default is \"view on GitHub \u2197\")\nexport MDXIFY_SOURCE_LINK_TEXT=\"\u29c9\"\nmdxify --all --root-module mypackage\n```\n\n## Features\n\n- **Fast AST-based parsing** - No module imports required\n- **MDX output** - Compatible with modern documentation frameworks\n- **Automatic navigation** - Generates hierarchical navigation structure\n- **Google-style docstrings** - Formats docstrings using Griffe\n- **Smart filtering** - Excludes private modules and known test patterns\n\n## Development\n\n```bash\n# Install development dependencies\nuv sync\n\n# Run tests\nuv run pytest\n\n# Run type checking\nuv run ty check\n\n# Run linting\nuv run ruff check src/ tests/\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate MDX API documentation from Python modules",
"version": "0.2.31",
"project_urls": {
"Code": "https://github.com/zzstoatzz/mdxify"
},
"split_keywords": [
"api",
" documentation",
" mdx",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9d624cd7b8ddaec838debc42c4593a5fad1772c5fdc84ee072e8f27ef724099f",
"md5": "f96198804f5be433a57a8f807ddc961a",
"sha256": "b29182c910dd9875a4074958d919efd627a54dd580f4e1435ef98ff98828516a"
},
"downloads": -1,
"filename": "mdxify-0.2.31-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f96198804f5be433a57a8f807ddc961a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 22968,
"upload_time": "2025-08-31T14:21:29",
"upload_time_iso_8601": "2025-08-31T14:21:29.398587Z",
"url": "https://files.pythonhosted.org/packages/9d/62/4cd7b8ddaec838debc42c4593a5fad1772c5fdc84ee072e8f27ef724099f/mdxify-0.2.31-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "105dd53a0a406ce87183706c920f15fab45e1e6ebf15e4efc9ba2f1b1de27e3a",
"md5": "cef61073e0c9529e1568eef7a9ec2dc8",
"sha256": "ff67dc4efcaf1179b57831903cb831bc85f182e02b50bfb64e57f3631f8144c7"
},
"downloads": -1,
"filename": "mdxify-0.2.31.tar.gz",
"has_sig": false,
"md5_digest": "cef61073e0c9529e1568eef7a9ec2dc8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 56135,
"upload_time": "2025-08-31T14:21:30",
"upload_time_iso_8601": "2025-08-31T14:21:30.667501Z",
"url": "https://files.pythonhosted.org/packages/10/5d/d53a0a406ce87183706c920f15fab45e1e6ebf15e4efc9ba2f1b1de27e3a/mdxify-0.2.31.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 14:21:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zzstoatzz",
"github_project": "mdxify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdxify"
}
