# sphinx-autodoc-fern
`sphinx-autodoc-fern` is a Sphinx extension that automatically generates API documentation for your Python packages with **Fern documentation format support**.
This is a fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) that adds powerful [Fern](https://buildwithfern.com) documentation generation capabilities.
## 🆕 New Fern Features
- **Fern-compatible Markdown output** - Generate documentation that works seamlessly with Fern
- **Enhanced parameter formatting** - Uses Fern's ParamField components for better API documentation
- **Smart callout handling** - Automatically converts NOTE: and WARNING: to Fern components
- **Beautiful tables** - Improved formatting for classes, functions, and module contents
Static analysis of Python code
: There is no need to install your package to generate the documentation, and `sphinx-autodoc2` will correctly handle `if TYPE_CHECKING` blocks and other typing only features.
: You can even document packages from outside the project (via `git clone`)!
Optimized for rebuilds
: Analysis of packages and file rendering are cached, so you can use `sphinx-autodoc2` in your development workflow.
Support for `__all__`
: `sphinx-autodoc2` can follow `__all__` variable, to only document the public API.
Support for both `rst` and `md` docstrings
: `sphinx-autodoc2` supports both `rst` and `md` ([MyST](https://myst-parser.readthedocs.io)) docstrings, which can be mixed within the same project.
Highly configurable
: `sphinx-autodoc-fern` is highly configurable, with many options to control the analysis and output of the documentation.
Fern Documentation Format Support
: Generate beautiful Fern-compatible documentation with enhanced formatting for parameters, callouts, and API references.
Decoupled analysis and rendering
: The analysis and rendering of the documentation are decoupled, and not dependent on Sphinx.
: This means that you can use `sphinx-autodoc-fern` to generate documentation outside of Sphinx (see the `autodoc2` command line tool).
## 🚀 Quick Start with Fern
```bash
pip install sphinx-autodoc-fern
```
To use the Fern renderer:
```python
from autodoc2.render.fern_ import FernRenderer
renderer = FernRenderer()
# Generate Fern-compatible documentation
```
Or use with the CLI:
```bash
autodoc2 --renderer fern your_package/
```
## Acknowledgments
This project is a fork of the excellent [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) by Chris Sewell. All credit for the core functionality goes to the original project.
## Design and comparison to sphinx-autoapi
The original sphinx-autodoc2 was created with the following goals:
- Static analysis of Python code, so things like `if TYPE_CHECKING` were handled correctly
- Support for MyST docstrings (see <https://github.com/executablebooks/MyST-Parser/issues/228>)
- Also support for transitioning from `rst` to `md`, i.e. mixing docstrings
- Make it simple and minimise the amount of configuration and rebuilds necessary
- Support for building public API via `__all__` variable
I am not looking to support other languages tha Python (at least for now).
[sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi) was a good candidate, but it had a few issues:
- It does not support MyST docstrings: <https://github.com/readthedocs/sphinx-autoapi/issues/287>
- It does not support the `__all__` very well: <https://github.com/readthedocs/sphinx-autoapi/issues/358>
- The analysis and rendering are coupled, making it difficult to test, modify and use outside of Sphinx
I've use a lot of their code, for the `astroid` static analysis, but I've made a number of "improvements":
- separating concerns: analysis and template writing
- type annotations for code base
- fixed `a | b` annotations inference
- added analysis of `functools.singledispatch` and their registers
- handling of `__all__`
- docstrings (and summaries) are now parsed with the correct source/line, i.e. warnings point to the correct location in the source file
- added `:canonical:` to `py` directives
- Moved away from using jinja templates, to using python functions
- IMO the templates were too complex and hard to read,
plus they do not benefit from any form of type checking, linting, etc.
- uses `list-table`, instead of `auto-summary` directive
## Development
All configuration is mainly in `pyproject.toml`.
Use [tox](https://tox.readthedocs.io/en/latest/) to run the tests.
```bash
pipx install tox
tox -av
```
Use [pre-commit](https://pre-commit.com/) to run the linters and formatters.
```bash
pipx install pre-commit
pre-commit run --all-files
# pre-commit install
```
[flit](https://flit.readthedocs.io/en/latest/) is used to build the package.
```bash
pipx install flit
flit build
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sphinx-autodoc2-fern",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sphinx, autodoc, extension, documentation, fern, api",
"author": null,
"author_email": "Ryan Stephen <ryanstep@buildwithfern.com>",
"download_url": "https://files.pythonhosted.org/packages/8f/83/37b4f10b35d30cc2b1cb34cc3863cbe0816b2f20e2679c2d0b009cccc82c/sphinx_autodoc2_fern-0.1.1.tar.gz",
"platform": null,
"description": "# sphinx-autodoc-fern\n\n`sphinx-autodoc-fern` is a Sphinx extension that automatically generates API documentation for your Python packages with **Fern documentation format support**.\n\nThis is a fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) that adds powerful [Fern](https://buildwithfern.com) documentation generation capabilities.\n\n## \ud83c\udd95 New Fern Features\n\n- **Fern-compatible Markdown output** - Generate documentation that works seamlessly with Fern\n- **Enhanced parameter formatting** - Uses Fern's ParamField components for better API documentation\n- **Smart callout handling** - Automatically converts NOTE: and WARNING: to Fern components\n- **Beautiful tables** - Improved formatting for classes, functions, and module contents\n\nStatic analysis of Python code\n\n: There is no need to install your package to generate the documentation, and `sphinx-autodoc2` will correctly handle `if TYPE_CHECKING` blocks and other typing only features.\n: You can even document packages from outside the project (via `git clone`)!\n\nOptimized for rebuilds\n\n: Analysis of packages and file rendering are cached, so you can use `sphinx-autodoc2` in your development workflow.\n\nSupport for `__all__`\n\n: `sphinx-autodoc2` can follow `__all__` variable, to only document the public API.\n\nSupport for both `rst` and `md` docstrings\n\n: `sphinx-autodoc2` supports both `rst` and `md` ([MyST](https://myst-parser.readthedocs.io)) docstrings, which can be mixed within the same project.\n\nHighly configurable\n\n: `sphinx-autodoc-fern` is highly configurable, with many options to control the analysis and output of the documentation.\n\nFern Documentation Format Support\n\n: Generate beautiful Fern-compatible documentation with enhanced formatting for parameters, callouts, and API references.\n\nDecoupled analysis and rendering\n\n: The analysis and rendering of the documentation are decoupled, and not dependent on Sphinx.\n: This means that you can use `sphinx-autodoc-fern` to generate documentation outside of Sphinx (see the `autodoc2` command line tool).\n\n## \ud83d\ude80 Quick Start with Fern\n\n```bash\npip install sphinx-autodoc-fern\n```\n\nTo use the Fern renderer:\n\n```python\nfrom autodoc2.render.fern_ import FernRenderer\n\nrenderer = FernRenderer()\n# Generate Fern-compatible documentation\n```\n\nOr use with the CLI:\n\n```bash\nautodoc2 --renderer fern your_package/\n```\n\n## Acknowledgments\n\nThis project is a fork of the excellent [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) by Chris Sewell. All credit for the core functionality goes to the original project.\n\n## Design and comparison to sphinx-autoapi\n\nThe original sphinx-autodoc2 was created with the following goals:\n\n- Static analysis of Python code, so things like `if TYPE_CHECKING` were handled correctly\n- Support for MyST docstrings (see <https://github.com/executablebooks/MyST-Parser/issues/228>)\n - Also support for transitioning from `rst` to `md`, i.e. mixing docstrings\n- Make it simple and minimise the amount of configuration and rebuilds necessary\n- Support for building public API via `__all__` variable\n\nI am not looking to support other languages tha Python (at least for now).\n\n[sphinx-autoapi](https://github.com/readthedocs/sphinx-autoapi) was a good candidate, but it had a few issues:\n\n- It does not support MyST docstrings: <https://github.com/readthedocs/sphinx-autoapi/issues/287>\n- It does not support the `__all__` very well: <https://github.com/readthedocs/sphinx-autoapi/issues/358>\n- The analysis and rendering are coupled, making it difficult to test, modify and use outside of Sphinx\n\nI've use a lot of their code, for the `astroid` static analysis, but I've made a number of \"improvements\":\n\n- separating concerns: analysis and template writing\n- type annotations for code base\n- fixed `a | b` annotations inference\n- added analysis of `functools.singledispatch` and their registers\n- handling of `__all__`\n- docstrings (and summaries) are now parsed with the correct source/line, i.e. warnings point to the correct location in the source file\n- added `:canonical:` to `py` directives\n- Moved away from using jinja templates, to using python functions\n - IMO the templates were too complex and hard to read,\n plus they do not benefit from any form of type checking, linting, etc.\n - uses `list-table`, instead of `auto-summary` directive\n\n## Development\n\nAll configuration is mainly in `pyproject.toml`.\n\nUse [tox](https://tox.readthedocs.io/en/latest/) to run the tests.\n\n```bash\npipx install tox\ntox -av\n```\n\nUse [pre-commit](https://pre-commit.com/) to run the linters and formatters.\n\n```bash\npipx install pre-commit\npre-commit run --all-files\n# pre-commit install\n```\n\n[flit](https://flit.readthedocs.io/en/latest/) is used to build the package.\n\n```bash\npipx install flit\nflit build\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Analyse a python project and create documentation for it.",
"version": "0.1.1",
"project_urls": {
"Home": "https://github.com/fern-api/sphinx-autodoc2-fern"
},
"split_keywords": [
"sphinx",
" autodoc",
" extension",
" documentation",
" fern",
" api"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2481c9d9009273f4cb66e2289ac961dd3791667066cb96ae3130ffbb156303a6",
"md5": "e86869bdea9e44372529a63136a0bf9d",
"sha256": "dcbdcc4d6b961e145371801d5e00f8082da8bfd46c01699f2e5bcd25434b6344"
},
"downloads": -1,
"filename": "sphinx_autodoc2_fern-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e86869bdea9e44372529a63136a0bf9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 53066,
"upload_time": "2025-10-22T02:19:39",
"upload_time_iso_8601": "2025-10-22T02:19:39.989098Z",
"url": "https://files.pythonhosted.org/packages/24/81/c9d9009273f4cb66e2289ac961dd3791667066cb96ae3130ffbb156303a6/sphinx_autodoc2_fern-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8f8337b4f10b35d30cc2b1cb34cc3863cbe0816b2f20e2679c2d0b009cccc82c",
"md5": "7f3a7ce6357744a90acfd58f6f71cd2a",
"sha256": "d28678b5c374144f5410a43c0044941967807b2c5a718cd25c105b9c0df8367b"
},
"downloads": -1,
"filename": "sphinx_autodoc2_fern-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7f3a7ce6357744a90acfd58f6f71cd2a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44007,
"upload_time": "2025-10-22T02:19:41",
"upload_time_iso_8601": "2025-10-22T02:19:41.085484Z",
"url": "https://files.pythonhosted.org/packages/8f/83/37b4f10b35d30cc2b1cb34cc3863cbe0816b2f20e2679c2d0b009cccc82c/sphinx_autodoc2_fern-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 02:19:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fern-api",
"github_project": "sphinx-autodoc2-fern",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sphinx-autodoc2-fern"
}
JSON
