Python autodoc for Fumadocs

See it in action here.

Features

• 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)

Installation

pnpm add fumadocs-python-autodoc shiki rehype-react unified

pip install fumadocs-autodoc

Usage

1. Export your source documentation to json. Assumes you have a python environment with fumadocs-autodoc and the package to document installed.

fumadocs-autodoc <pkg_name> --dir ./lib

2. Add a config file fumapy.config.ts in the root of your project. Here you specify each package to document:

// 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:

// 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:

// 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 = (
    <AutoDocLayout
      sources={autodocSources}
      shikiConfig={config.shiki}
      slug={slug}
      {...baseOptions}
    >
      {children}
    </AutoDocLayout>
  );
  return comp;
}

// 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:

// 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.

Disclaimer

• 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.