Merge pull request #6 from fern-api/overhaul

feat: removed all sphinx and kept it to Fern

Author: Ryan-Amirthan

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
 
-exclude: ^tests/.*\.md|tests/.*\.rst|tests/.*\.xml|docs/apidocs/.*
+exclude: ^tests/.*\.md
 
 repos:
     - repo: https://github.com/pre-commit/pre-commit-hooks
@@ -23,5 +23,5 @@ repos:
       hooks:
       - id: mypy
         args: [--config-file=pyproject.toml]
-        additional_dependencies: ["sphinx~=7.3", "typer[all]"]
+        additional_dependencies: ["typer[all]"]
         exclude: ^tests/.*\.py$

.readthedocs.yml

@@ -1,64 +1,37 @@
-# sphinx-autodoc2-fern
+# py2fern
 
-Generate Fern-compatible API documentation from Python packages using static analysis.
+Generate [Fern](https://buildwithfern.com) API documentation from Python packages using static analysis.
 
-Fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) with [Fern](https://buildwithfern.com) output support.
+Simplified fork of [`sphinx-autodoc2`](https://github.com/sphinx-extensions2/sphinx-autodoc2) focused purely on **Python → Fern markdown** output.
 
 ## Installation
 
 ```bash
-pip install sphinx-autodoc2-fern
+pipx install py2fern
 ```
 
 ## Usage
 
-Generate Fern-compatible markdown documentation:
+Generate Fern markdown documentation:
 
 ```bash
-autodoc2 --renderer fern /path/to/your/package
+py2fern write /path/to/your/package
+```
+
+Specify output directory:
+
+```bash
+py2fern write /path/to/your/package --output ./docs/api
 ```
 
 This creates:
-- Markdown files with Fern-compatible frontmatter and slugs
-- `navigation.yml` for Fern docs structure
-- Tables with proper linking and descriptions
+- **MDX files** with Fern-compatible frontmatter and slugs
+- **`navigation.yml`** for Fern docs structure 
 
 ## 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`.