Python autodoc for FumaDocs
npm install fumadocs-python-autodocSee it in action here.
- Fully autogenerated API documentation for entire packages
- Cross-references to itself and the sources specified in the config
- Includes source code in the documentation
- Generates a page for each module
Easily add source code documentation to your Fumadocs documentation site (assumes you have Fumadocs already set up):
- Custom source for fumadocs (includes structured data for search implementation)
1. Export your source documentation to json. Assumes you have a python environment with fumadocs-autodoc and the package to document installed.
``bash`
fumadocs-autodoc
2. Add a config file fumapy.config.ts in the root of your project. Here you specify each package to document:
`ts
// fumapy.config.ts
import { Config } from "fumadocs-python-autodoc/source";
const config: Config = {
shiki: {
lang: "python",
themes: {
dark: "vitesse-dark",
light: "vitesse-light",
},
},
jsonPath: "lib",
sources: {
bamboost: {
baseUrl: "autodoc",
title: "API Reference",
pkgName: "bamboost",
sortClassMethods: true,
gitUrl: "https://gitlab.com/cmbm-ethz/bamboost/-/blob/next/bamboost",
excludeModules: ["bamboost._version"],
},
},
};
export default config;
`
3. Add a source in lib:
`ts
// lib/autodocSources.ts
import config from "@/fumapy.config";
import { getSources } from "fumadocs-python-autodoc/source";
import {
setShikiConfigContext,
setSourcesContext,
} from "fumadocs-python-autodoc/components";
export const autodocSources = getSources(config);
setSourcesContext(autodocSources);
setShikiConfigContext(config.shiki);
`
4. Add a dynamic route in app/(apidocs)/[...slug] which handles the autodoc for all specified packages:
`ts
// app/(apidocs)/[...slug]/layout.tsx
import { ReactNode } from "react";
import { AutoDocLayout } from "fumadocs-python-autodoc/components";
import { baseOptions } from "@/app/layout.config";
import { autodocSources } from "@/lib/autodocSources";
import config from "@/fumapy.config";
export default async function Layout({
children,
params,
}: {
children: ReactNode;
params: Promise<{ slug?: string[] }>;
}) {
const { slug } = await params;
const comp = (
shikiConfig={config.shiki}
slug={slug}
{...baseOptions}
>
{children}
);
return comp;
}
`
`ts
// app/(apidocs)/[...slug]/page.tsx
import { autodocSources } from "@/lib/autodocSources";
import { makePage } from "fumadocs-python-autodoc/components";
const { Page, generateStaticParams, generateMetadata } =
makePage(autodocSources);
export default Page;
export { generateStaticParams, generateMetadata };
`
5. Add stylesheet:
`css``
// global.css
@import "fumadocs-python-autodoc/preset.css";
5. Add links to your layout and homepage. That's it.
See the example app in this repo for a working example.
- Docstrings are rendered using a Markdown pipeline. Assumes your docstrings are in Markdown format.
- In terms of functionality this does not compete with mature autodocumentation tools like Sphinx or MkDocs.
- This is an early adaption of my own workflow for bamboost. Contributions are welcome.
- I am inexperienced with web development and typescript. Please be kind.