AstroAutodoc(feat[rst-lite]): Render docstrings with rst-lite

why: Replace docutils HTML with deterministic RST-lite rendering for docstrings.
what:
- add rst-lite docstring rendering helper and tests
- wire render mode into loadApiPackage options and docs app
- add rst-lite dependency for astro-autodoc

Author: tony

astro/apps/docs/src/lib/api.ts

@@ -32,6 +32,7 @@ export const getApiModel = async (): Promise<ApiPackage> => {
     introspectPackage: 'libtmux',
     annotationFormat: 'string',
     mockImports: ['pytest'],
+    docstringRenderer: 'rst-lite',
   })
 
   return cached

astro/packages/astro-autodoc/package.json

@@ -24,7 +24,8 @@
     "@libtmux/api-model": "workspace:*",
     "@libtmux/py-bridge": "workspace:*",
     "@libtmux/py-introspect": "workspace:*",
-    "@libtmux/py-parse": "workspace:*"
+    "@libtmux/py-parse": "workspace:*",
+    "@libtmux/rst-lite": "workspace:*"
   },
   "peerDependencies": {
     "astro": "^5.0.0"

astro/packages/astro-autodoc/src/docstrings.ts

@@ -0,0 +1,79 @@
+import type { ApiClass, ApiFunction, ApiMethod, ApiModule, ApiPackage, ApiVariable } from '@libtmux/api-model'
+import { parseRst, type RoleResolver, renderHtml } from '@libtmux/rst-lite'
+
+export type DocstringRenderMode = 'introspect' | 'rst-lite' | 'none'
+
+export type DocstringRenderOptions = {
+  mode?: DocstringRenderMode
+  roleResolver?: RoleResolver
+}
+
+const shouldRender = (docstring: string | null, format: string): boolean => {
+  if (!docstring) {
+    return false
+  }
+  if (format === 'markdown') {
+    return false
+  }
+  return true
+}
+
+const renderDocstring = (docstring: string | null, format: string, roleResolver?: RoleResolver): string | null => {
+  if (!shouldRender(docstring, format)) {
+    return null
+  }
+  const doc = parseRst(docstring ?? '')
+  return renderHtml(doc, { roleResolver })
+}
+
+const applyToFunction = (fn: ApiFunction, roleResolver?: RoleResolver): ApiFunction => {
+  return {
+    ...fn,
+    docstringHtml: renderDocstring(fn.docstring, fn.docstringFormat, roleResolver),
+  }
+}
+
+const applyToMethod = (method: ApiMethod, roleResolver?: RoleResolver): ApiMethod => {
+  return {
+    ...method,
+    docstringHtml: renderDocstring(method.docstring, method.docstringFormat, roleResolver),
+  }
+}
+
+const applyToVariable = (variable: ApiVariable, roleResolver?: RoleResolver): ApiVariable => {
+  return {
+    ...variable,
+    docstringHtml: renderDocstring(variable.docstring, variable.docstringFormat, roleResolver),
+  }
+}
+
+const applyToClass = (klass: ApiClass, roleResolver?: RoleResolver): ApiClass => {
+  return {
+    ...klass,
+    docstringHtml: renderDocstring(klass.docstring, klass.docstringFormat, roleResolver),
+    methods: klass.methods.map((method) => applyToMethod(method, roleResolver)),
+    attributes: klass.attributes.map((attribute) => applyToVariable(attribute, roleResolver)),
+  }
+}
+
+const applyToModule = (module: ApiModule, roleResolver?: RoleResolver): ApiModule => {
+  return {
+    ...module,
+    docstringHtml: renderDocstring(module.docstring, module.docstringFormat, roleResolver),
+    classes: module.classes.map((klass) => applyToClass(klass, roleResolver)),
+    functions: module.functions.map((fn) => applyToFunction(fn, roleResolver)),
+    variables: module.variables.map((variable) => applyToVariable(variable, roleResolver)),
+  }
+}
+
+export const renderDocstrings = (api: ApiPackage, options: DocstringRenderOptions = {}): ApiPackage => {
+  const mode = options.mode ?? 'introspect'
+  if (mode !== 'rst-lite') {
+    return api
+  }
+
+  return {
+    ...api,
+    modules: api.modules.map((module) => applyToModule(module, options.roleResolver)),
+  }
+}

astro/packages/astro-autodoc/src/index.ts

@@ -16,5 +16,6 @@ export const autodocComponents = {
   Docstring,
 }
 
+export * from './docstrings.ts'
 export * from './load.ts'
 export * from './utils.ts'

astro/packages/astro-autodoc/src/load.ts

@@ -3,6 +3,8 @@ import { buildApiPackage } from '@libtmux/api-model'
 import type { PythonCommand } from '@libtmux/py-bridge'
 import { introspectPackage } from '@libtmux/py-introspect'
 import { scanPythonPaths } from '@libtmux/py-parse'
+import type { RoleResolver } from '@libtmux/rst-lite'
+import { type DocstringRenderMode, renderDocstrings } from './docstrings.ts'
 
 export type LoadApiOptions = {
   name: string
@@ -15,6 +17,8 @@ export type LoadApiOptions = {
   annotationFormat?: 'string' | 'value'
   mockImports?: string[]
   autodocMock?: boolean
+  docstringRenderer?: DocstringRenderMode
+  docstringRoleResolver?: RoleResolver
   pythonCommand?: PythonCommand
 }
 
@@ -39,11 +43,16 @@ export const loadApiPackage = async (options: LoadApiOptions): Promise<ApiPackag
       ).modules
     : undefined
 
-  return buildApiPackage(modules, {
+  const api = buildApiPackage(modules, {
     name: options.name,
     root: options.root,
     includePrivate: options.includePrivate,
     generatedAt: options.generatedAt,
     introspection,
   })
+
+  return renderDocstrings(api, {
+    mode: options.docstringRenderer,
+    roleResolver: options.docstringRoleResolver,
+  })
 }

astro/packages/astro-autodoc/tests/docstrings.test.ts

@@ -0,0 +1,42 @@
+import type { ApiPackage } from '@libtmux/api-model'
+import { describe, expect, it } from 'vitest'
+import { renderDocstrings } from '../src/docstrings.ts'
+
+const location = {
+  lineno: 1,
+  colOffset: 0,
+  endLineno: null,
+  endColOffset: null,
+}
+
+const sampleApi: ApiPackage = {
+  name: 'demo',
+  root: '/demo',
+  generatedAt: '2026-01-05T00:00:00.000Z',
+  modules: [
+    {
+      kind: 'module',
+      name: 'demo',
+      qualname: 'demo',
+      docstring: 'Hello *world*',
+      docstringFormat: 'rst',
+      docstringHtml: null,
+      summary: null,
+      isPrivate: false,
+      location,
+      path: '/demo/__init__.py',
+      exports: [],
+      imports: [],
+      classes: [],
+      functions: [],
+      variables: [],
+    },
+  ],
+}
+
+describe('renderDocstrings', () => {
+  it('renders rst-lite HTML for module docstrings', () => {
+    const rendered = renderDocstrings(sampleApi, { mode: 'rst-lite' })
+    expect(rendered.modules[0]?.docstringHtml).toMatchInlineSnapshot('"<p>Hello <em>world</em></p>"')
+  })
+})