| Name | mdxify JSON |
| Version |
0.2.19
JSON |
| download |
| home_page | None |
| Summary | Generate MDX API documentation from Python modules |
| upload_time | 2025-07-10 13:27:23 |
| 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.
## 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/3d/44/852dcc009dfcaa8d1762933eeb5dd0fae8fdb97b1405605af63d71365edf/mdxify-0.2.19.tar.gz",
"platform": null,
"description": "# mdxify\n\nGenerate MDX API documentation from Python modules with automatic navigation structure.\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.19",
"project_urls": {
"Code": "https://github.com/zzstoatzz/mdxify"
},
"split_keywords": [
"api",
" documentation",
" mdx",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8aef173993b4ccb0e9e8f7d9cbb7715a9f78e1810ffdfc6737dbe546fd4d749b",
"md5": "23cd3875bff1ef25bcac983dc9649b18",
"sha256": "be852d34bc544d244b85b3b64baf2a7a14795b6fc98777260e72dd6089aee11f"
},
"downloads": -1,
"filename": "mdxify-0.2.19-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23cd3875bff1ef25bcac983dc9649b18",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 18372,
"upload_time": "2025-07-10T13:27:22",
"upload_time_iso_8601": "2025-07-10T13:27:22.252040Z",
"url": "https://files.pythonhosted.org/packages/8a/ef/173993b4ccb0e9e8f7d9cbb7715a9f78e1810ffdfc6737dbe546fd4d749b/mdxify-0.2.19-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "3d44852dcc009dfcaa8d1762933eeb5dd0fae8fdb97b1405605af63d71365edf",
"md5": "1def8374c3c747dc62481b521483b458",
"sha256": "6abd30e953969ef10bfa98ed779ca3d2653ed0da1e68f37c8597a61d022d5a62"
},
"downloads": -1,
"filename": "mdxify-0.2.19.tar.gz",
"has_sig": false,
"md5_digest": "1def8374c3c747dc62481b521483b458",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 53629,
"upload_time": "2025-07-10T13:27:23",
"upload_time_iso_8601": "2025-07-10T13:27:23.172003Z",
"url": "https://files.pythonhosted.org/packages/3d/44/852dcc009dfcaa8d1762933eeb5dd0fae8fdb97b1405605af63d71365edf/mdxify-0.2.19.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-10 13:27:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zzstoatzz",
"github_project": "mdxify",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mdxify"
}
