fumero 0.1.0__tar.gz

fumero-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Important Looking Pirates AB
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fumero-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: fumero
+Version: 0.1.0
+Summary: Generate a Fumadocs API reference from a Python module.
+Keywords: api-reference,documentation,mdx
+Author: Fredrik Brännbacka, Ludvig Holmkvist
+Author-email: Fredrik Brännbacka <fredrik.brannbacka@ilpvfx.com>, Ludvig Holmkvist <ludvig.holmkvist@ilpvfx.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Dist: griffe>=2.1.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Python: >=3.11
+Project-URL: Documentation, https://ilpvfx.github.io/fumero/
+Project-URL: Repository, https://github.com/ilpvfx/fumero
+Project-URL: Changelog, https://github.com/ilpvfx/fumero/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+<div align="center">
+  <h1>Fumero</h1>
+  <p><strong>Generate a Fumadocs API reference from a Python module.</strong></p>
+</div>
+
+Fumero reads an importable module with [griffe](https://mkdocstrings.github.io/griffe/) and writes
+a [Fumadocs](https://fumadocs.dev) API reference: one page per module and one per class, alongside
+the React components that render them.
+
+The reference is generated from the code. Signatures, type annotations and default values are read
+from the source, and the prose is taken from the docstrings. Nothing is restated by hand, so the
+reference cannot fall out of step with the code it documents.
+
+## Install
+
+```sh
+uv add fumero --dev  # or pip install fumero
+```
+
+## Quick start
+
+Install the components into the docs app that will render the output:
+
+```sh
+fumero init src/components/mdx
+```
+
+Register them once, so every generated page knows how to render itself:
+
+```tsx
+// src/mdx-components.tsx
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import * as Pdx from '@/components/mdx/pdx-components';
+
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+  return { ...defaultMdxComponents, ...Pdx, ...components };
+}
+```
+
+The loader plugin that came with them labels the sidebar entries that lead to a module:
+
+```ts
+// src/lib/source.ts
+import { fumeroPlugin } from '@/components/mdx/pdx-plugin';
+
+export const source = loader({
+  plugins: [fumeroPlugin()],
+  baseUrl: '/docs',
+  source: docs.toFumadocsSource(),
+});
+```
+
+A generated page carries its kind under `_fumero`, and Fumadocs keeps only the frontmatter its schema
+names, so let the rest through:
+
+```ts
+// source.config.ts
+schema: pageSchema.loose(),
+```
+
+Then document a module:
+
+```sh
+fumero generate example --output content/docs/api --base-url /api --with-meta
+```
+
+## Configuration
+
+Every option is a flag on `fumero generate` and a key in a `[tool.fumero]` table. Options that do
+not change between runs belong in `pyproject.toml`:
+
+```toml
+[tool.fumero]
+output = "content/docs/api"
+base-url = "/api"
+exclude = ["example.internal", "*.tests"]
+with-meta = true
+```
+
+A flag overrides the file, which overrides the defaults.
+
+## Documentation
+
+The full documentation lives at [here](https://ilpvfx.github.io/fumero/). Fumero documents
+itself, so the API reference there is a working example of the output as much as it is a reference.
+
+## Development
+
+This project uses [devenv](https://devenv.sh) to manage the development environment. It sets up
+Python, uv, and everything else you need.
+
+```sh
+# Install devenv if you haven't already
+# https://devenv.sh/getting-started/
+
+# Enter the dev shell - this installs all dependencies automatically
+devenv shell
+```
+
+Once you are in the shell, lint, type check, and test with:
+
+```sh
+uv run ruff check
+uv run ty check
+uv run pytest
+```

fumero-0.1.0/README.md

@@ -0,0 +1,106 @@
+<div align="center">
+  <h1>Fumero</h1>
+  <p><strong>Generate a Fumadocs API reference from a Python module.</strong></p>
+</div>
+
+Fumero reads an importable module with [griffe](https://mkdocstrings.github.io/griffe/) and writes
+a [Fumadocs](https://fumadocs.dev) API reference: one page per module and one per class, alongside
+the React components that render them.
+
+The reference is generated from the code. Signatures, type annotations and default values are read
+from the source, and the prose is taken from the docstrings. Nothing is restated by hand, so the
+reference cannot fall out of step with the code it documents.
+
+## Install
+
+```sh
+uv add fumero --dev  # or pip install fumero
+```
+
+## Quick start
+
+Install the components into the docs app that will render the output:
+
+```sh
+fumero init src/components/mdx
+```
+
+Register them once, so every generated page knows how to render itself:
+
+```tsx
+// src/mdx-components.tsx
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import * as Pdx from '@/components/mdx/pdx-components';
+
+export function getMDXComponents(components?: MDXComponents): MDXComponents {
+  return { ...defaultMdxComponents, ...Pdx, ...components };
+}
+```
+
+The loader plugin that came with them labels the sidebar entries that lead to a module:
+
+```ts
+// src/lib/source.ts
+import { fumeroPlugin } from '@/components/mdx/pdx-plugin';
+
+export const source = loader({
+  plugins: [fumeroPlugin()],
+  baseUrl: '/docs',
+  source: docs.toFumadocsSource(),
+});
+```
+
+A generated page carries its kind under `_fumero`, and Fumadocs keeps only the frontmatter its schema
+names, so let the rest through:
+
+```ts
+// source.config.ts
+schema: pageSchema.loose(),
+```
+
+Then document a module:
+
+```sh
+fumero generate example --output content/docs/api --base-url /api --with-meta
+```
+
+## Configuration
+
+Every option is a flag on `fumero generate` and a key in a `[tool.fumero]` table. Options that do
+not change between runs belong in `pyproject.toml`:
+
+```toml
+[tool.fumero]
+output = "content/docs/api"
+base-url = "/api"
+exclude = ["example.internal", "*.tests"]
+with-meta = true
+```
+
+A flag overrides the file, which overrides the defaults.
+
+## Documentation
+
+The full documentation lives at [here](https://ilpvfx.github.io/fumero/). Fumero documents
+itself, so the API reference there is a working example of the output as much as it is a reference.
+
+## Development
+
+This project uses [devenv](https://devenv.sh) to manage the development environment. It sets up
+Python, uv, and everything else you need.
+
+```sh
+# Install devenv if you haven't already
+# https://devenv.sh/getting-started/
+
+# Enter the dev shell - this installs all dependencies automatically
+devenv shell
+```
+
+Once you are in the shell, lint, type check, and test with:
+
+```sh
+uv run ruff check
+uv run ty check
+uv run pytest
+```

fumero-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "fumero"
+version = "0.1.0"
+description = "Generate a Fumadocs API reference from a Python module."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "api-reference",
+    "documentation",
+    "mdx",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+    "Typing :: Typed",
+]
+dependencies = [
+    "griffe>=2.1.0",
+    "jinja2>=3.1.6",
+]
+
+[[project.authors]]
+name = "Fredrik Brännbacka"
+email = "fredrik.brannbacka@ilpvfx.com"
+
+[[project.authors]]
+name = "Ludvig Holmkvist"
+email = "ludvig.holmkvist@ilpvfx.com"
+
+[project.urls]
+Documentation = "https://ilpvfx.github.io/fumero/"
+Repository = "https://github.com/ilpvfx/fumero"
+Changelog = "https://github.com/ilpvfx/fumero/blob/main/CHANGELOG.md"
+
+[project.scripts]
+fumero = "fumero.tools.fumero:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+    "ruff>=0.16.0",
+    "ty>=0.0.63",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.fumero]
+base-url = "/api"
+clean = true
+output = "docs/content/docs/api"
+with-meta = true
+
+[tool.ruff]
+line-length = 100

fumero-0.1.0/pyproject.toml.orig

@@ -0,0 +1,55 @@
+[project]
+name = "fumero"
+version = "0.1.0"
+description = "Generate a Fumadocs API reference from a Python module."
+readme = "README.md"
+authors = [
+  { name = "Fredrik Brännbacka", email = "fredrik.brannbacka@ilpvfx.com" },
+  { name = "Ludvig Holmkvist", email = "ludvig.holmkvist@ilpvfx.com" },
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["api-reference", "documentation", "mdx"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+  "Typing :: Typed",
+]
+dependencies = [
+  "griffe>=2.1.0",
+  "jinja2>=3.1.6",
+]
+
+[project.urls]
+Documentation = "https://ilpvfx.github.io/fumero/"
+Repository = "https://github.com/ilpvfx/fumero"
+Changelog = "https://github.com/ilpvfx/fumero/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "pytest>=9.1.1",
+  "ruff>=0.16.0",
+  "ty>=0.0.63",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.25,<0.12.0"]
+build-backend = "uv_build"
+
+[project.scripts]
+fumero = "fumero.tools.fumero:main"
+
+[tool.fumero]
+base-url = "/api"
+clean = true
+output = "docs/content/docs/api"
+with-meta = true
+
+[tool.ruff]
+line-length = 100

fumero-0.1.0/src/fumero/__init__.py

@@ -0,0 +1,72 @@
+"""Turn a Python module into a Fumadocs API reference.
+
+fumero reads a module with [griffe][griffe], writes the MDX a Fumadocs site renders, and ships the
+React components that render it. Signatures, type annotations and default values are read from the
+source, and the prose is taken from the docstrings.
+
+### One call
+
+```python
+from pathlib import Path
+
+import fumero
+
+result = fumero.generate(
+    "example",
+    fumero.Config(output=Path("content/docs/api"), base_url="/docs/api", clean=True),
+)
+```
+
+Nothing here prints and nothing exits. [`generate`] hands back a [`Result`] naming every page it
+wrote and every reference it could not resolve, which leaves a build script free to decide what
+that is worth:
+
+```python
+if not result.ok:
+    raise SystemExit("the reference has broken links")
+```
+
+[`ModuleNotFound`] is the one error to expect. Documenting a module means importing it, so a
+module that will not import is the end of the run rather than a page with gaps in it.
+
+### A layer down
+
+[`generate`] is two steps taken together, and they come apart when several modules are documented
+into one site, or when the tree is already loaded:
+
+```python
+config = fumero.Config(base_url="/docs/api")
+module = fumero.load_module("example", config)
+result = fumero.Renderer(config).render(module, Path("content/docs/api"))
+```
+
+A [`LinkTable`] is collected across the whole tree before anything is written, which is what lets
+a page reference a symbol whose own page is written later.
+
+[griffe]: https://mkdocstrings.github.io/griffe/
+"""
+
+from . import error, model
+from .component import component_source, init, plugin_source
+from .config import Config, Dialect
+from .link import LinkTable
+from .mdx import encode_text
+from .parse import load_module
+from .render import Renderer, Result, UnresolvedLink, generate
+
+__all__ = [
+    "Config",
+    "Dialect",
+    "LinkTable",
+    "Renderer",
+    "Result",
+    "UnresolvedLink",
+    "component_source",
+    "encode_text",
+    "error",
+    "generate",
+    "init",
+    "load_module",
+    "model",
+    "plugin_source",
+]

fumero-0.1.0/src/fumero/__main__.py

@@ -0,0 +1,7 @@
+"""Run the command line as `python -m fumero`."""
+
+import sys
+
+from .tools.fumero import main
+
+sys.exit(main())