|
1 | | -# sphinx-autodoc-fern |
| 1 | +# sphinx-autodoc2-fern |
2 | 2 |
|
3 | | -`sphinx-autodoc-fern` is a Sphinx extension that automatically generates API documentation for your Python packages with **Fern documentation format support**. |
| 3 | +Generate Fern-compatible API documentation from Python packages using static analysis. |
4 | 4 |
|
5 | | -This is a fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) that adds powerful [Fern](https://buildwithfern.com) documentation generation capabilities. |
| 5 | +Fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) with [Fern](https://buildwithfern.com) output support. |
6 | 6 |
|
7 | | -## 🆕 New Fern Features |
8 | | - |
9 | | -- **Fern-compatible Markdown output** - Generate documentation that works seamlessly with Fern |
10 | | -- **Enhanced parameter formatting** - Uses Fern's ParamField components for better API documentation |
11 | | -- **Smart callout handling** - Automatically converts NOTE: and WARNING: to Fern components |
12 | | -- **Beautiful tables** - Improved formatting for classes, functions, and module contents |
13 | | - |
14 | | -Static analysis of Python code |
15 | | - |
16 | | -: 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. |
17 | | -: You can even document packages from outside the project (via `git clone`)! |
18 | | - |
19 | | -Optimized for rebuilds |
20 | | - |
21 | | -: Analysis of packages and file rendering are cached, so you can use `sphinx-autodoc2` in your development workflow. |
22 | | - |
23 | | -Support for `__all__` |
24 | | - |
25 | | -: `sphinx-autodoc2` can follow `__all__` variable, to only document the public API. |
26 | | - |
27 | | -Support for both `rst` and `md` docstrings |
28 | | - |
29 | | -: `sphinx-autodoc2` supports both `rst` and `md` ([MyST](https://myst-parser.readthedocs.io)) docstrings, which can be mixed within the same project. |
30 | | - |
31 | | -Highly configurable |
32 | | - |
33 | | -: `sphinx-autodoc-fern` is highly configurable, with many options to control the analysis and output of the documentation. |
34 | | - |
35 | | -Fern Documentation Format Support |
36 | | - |
37 | | -: Generate beautiful Fern-compatible documentation with enhanced formatting for parameters, callouts, and API references. |
38 | | - |
39 | | -Decoupled analysis and rendering |
40 | | - |
41 | | -: The analysis and rendering of the documentation are decoupled, and not dependent on Sphinx. |
42 | | -: This means that you can use `sphinx-autodoc-fern` to generate documentation outside of Sphinx (see the `autodoc2` command line tool). |
43 | | - |
44 | | -## 🚀 Quick Start with Fern |
| 7 | +## Installation |
45 | 8 |
|
46 | 9 | ```bash |
47 | | -pip install sphinx-autodoc-fern |
| 10 | +pip install sphinx-autodoc2-fern |
48 | 11 | ``` |
49 | 12 |
|
50 | | -To use the Fern renderer: |
51 | | - |
52 | | -```python |
53 | | -from autodoc2.render.fern_ import FernRenderer |
| 13 | +## Usage |
54 | 14 |
|
55 | | -renderer = FernRenderer() |
56 | | -# Generate Fern-compatible documentation |
57 | | -``` |
58 | | - |
59 | | -Or use with the CLI: |
| 15 | +Generate Fern-compatible markdown documentation: |
60 | 16 |
|
61 | 17 | ```bash |
62 | | -autodoc2 --renderer fern your_package/ |
| 18 | +autodoc2 --renderer fern /path/to/your/package |
63 | 19 | ``` |
64 | 20 |
|
| 21 | +This creates: |
| 22 | +- Markdown files with Fern-compatible frontmatter and slugs |
| 23 | +- `navigation.yml` for Fern docs structure |
| 24 | +- Tables with proper linking and descriptions |
| 25 | + |
65 | 26 | ## Acknowledgments |
66 | 27 |
|
67 | 28 | 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. |
|
0 commit comments