@usecross/docs 0.11.0 → 0.12.0

package/src/components/api/FunctionDoc.tsx

@@ -0,0 +1,130 @@
+import type { GriffeFunction, GriffeDocstringElement } from '../../types'
+import { Signature } from './Signature'
+import { Docstring } from './Docstring'
+import { ParameterTable } from './ParameterTable'
+import { CodeSpan } from './CodeSpan'
+import { Markdown } from '../Markdown'
+
+interface FunctionDocProps {
+  fn: GriffeFunction
+  /** Whether this is a method (inside a class) */
+  isMethod?: boolean
+  /** Show function name as title */
+  showName?: boolean
+  /** GitHub repo URL for source links */
+  githubUrl?: string
+  /** Additional CSS class */
+  className?: string
+  /** Override display path (e.g., for aliases to show alias name instead of target path) */
+  displayPath?: string
+}
+
+/**
+ * Renders documentation for a function or method matching strawberry.rocks design.
+ */
+export function FunctionDoc({ fn, isMethod = false, showName = true, githubUrl, className = '', displayPath }: FunctionDocProps) {
+  const hasParams = fn.parameters && fn.parameters.filter(p => p.name !== 'self').length > 0
+
+  // Get returns description from docstring
+  const returnsSection = fn.docstring?.parsed?.find(s => s.kind === 'returns')
+  const returnsValue = returnsSection?.value
+  const returnsDescription = Array.isArray(returnsValue)
+    ? (returnsValue[0] as GriffeDocstringElement)?.description
+    : undefined
+
+  // Get additional text sections (examples, notes, etc.) - all text sections after the first
+  const textSections = fn.docstring?.parsed?.filter(s => s.kind === 'text') || []
+  const additionalTextSections = textSections.slice(1) // Skip first (description)
+
+  // Get relative filepath for display (prefer package-relative path)
+  const relativeFilepath = fn.relative_package_filepath || fn.relative_filepath || fn.filepath
+
+  // Build GitHub URL for source link
+  const githubSourceUrl = githubUrl && relativeFilepath && fn.lineno
+    ? `${githubUrl}/blob/main/${relativeFilepath}#L${fn.lineno}-L${fn.endlineno || fn.lineno}`
+    : undefined
+
+  return (
+    <article id={fn.name} className={`scroll-mt-20 ${className}`}>
+      {/* Function name/title */}
+      {showName && (
+        <h1 className="font-mono text-2xl font-normal text-gray-900 dark:text-white mb-8">
+          {displayPath || fn.path || fn.name}
+        </h1>
+      )}
+
+      {/* Docstring - description text only */}
+      {fn.docstring && (
+        <div className="mb-6">
+          <Docstring docstring={fn.docstring} showOnlyText />
+        </div>
+      )}
+
+      {/* Returns section */}
+      {returnsDescription && (
+        <section className="mb-6">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+            Returns:
+          </h2>
+          <p className="text-gray-700 dark:text-gray-300">
+            {returnsDescription}
+          </p>
+        </section>
+      )}
+
+      {/* Signature section */}
+      <section className="mb-6">
+        <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+          Signature:
+        </h2>
+        <Signature fn={fn} />
+      </section>
+
+      {/* Parameters section */}
+      {hasParams && (
+        <section id="parameters" className="mb-6">
+          <h2 className="text-2xl font-bold text-gray-900 dark:text-white mb-4">
+            Parameters:
+          </h2>
+          <ParameterTable
+            parameters={fn.parameters!}
+            docstringSections={fn.docstring?.parsed}
+          />
+        </section>
+      )}
+
+      {/* Additional text sections (examples, notes, etc.) */}
+      {additionalTextSections.length > 0 && (
+        <section className="mb-6 prose prose-sm dark:prose-invert max-w-none">
+          {additionalTextSections.map((section, i) => (
+            <Markdown key={i} content={section.value as string} />
+          ))}
+        </section>
+      )}
+
+      {/* Footer with file path and GitHub link (only for top-level functions) */}
+      {!isMethod && relativeFilepath && (
+        <footer className="mt-8 pt-6 border-t border-gray-200 dark:border-gray-700 space-y-4">
+          <p className="flex items-center gap-2">
+            <span className="text-sm font-semibold text-gray-500 dark:text-gray-400 uppercase tracking-wide">
+              File path:
+            </span>
+            <CodeSpan allowCopy>{relativeFilepath}</CodeSpan>
+          </p>
+          {githubSourceUrl && (
+            <p>
+              <a
+                href={githubSourceUrl}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="text-sm font-semibold text-gray-500 hover:text-gray-700 dark:text-gray-400 dark:hover:text-gray-200 uppercase tracking-wide"
+              >
+                Open in GitHub
+              </a>
+            </p>
+          )}
+        </footer>
+      )}
+    </article>
+  )
+}

package/src/components/api/ModuleDoc.tsx

@@ -0,0 +1,298 @@
+import { Link } from '@inertiajs/react'
+import type { GriffeModule, GriffeClass, GriffeFunction, GriffeAttribute, GriffeMember, GriffeExpression } from '../../types'
+import { Docstring } from './Docstring'
+import { ClassDoc } from './ClassDoc'
+import { FunctionDoc } from './FunctionDoc'
+
+/**
+ * Safely render a Griffe expression or value to a string
+ */
+function renderValue(value: string | GriffeExpression | undefined): string {
+  if (!value) return ''
+  if (typeof value === 'string') return value
+  // Handle Griffe expression objects
+  if (value.str) return value.str
+  if (value.canonical) return value.canonical
+
+  const exprAny = value as any
+
+  // Handle ExprName with member reference
+  if (value.name && typeof value.name === 'string') return value.name
+
+  // Handle ExprBoolOp (like `config or StrawberryConfig()`)
+  if (exprAny.cls === 'ExprBoolOp' && exprAny.operator && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderValue(v)).join(` ${exprAny.operator} `)
+  }
+
+  // Handle ExprBinOp (like `type | None`)
+  if (exprAny.cls === 'ExprBinOp' && exprAny.left && exprAny.right) {
+    const left = renderValue(exprAny.left)
+    const right = renderValue(exprAny.right)
+    const op = exprAny.operator || '|'
+    return `${left} ${op} ${right}`
+  }
+
+  // Handle ExprCall (like `StrawberryConfig()`)
+  if (exprAny.cls === 'ExprCall' && exprAny.function) {
+    const funcName = renderValue(exprAny.function)
+    const args = Array.isArray(exprAny.arguments)
+      ? exprAny.arguments.map((a: any) => renderValue(a)).join(', ')
+      : ''
+    return `${funcName}(${args})`
+  }
+
+  // Handle ExprAttribute (like contextlib.asynccontextmanager)
+  if (exprAny.cls === 'ExprAttribute' && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderValue(v)).join('.')
+  }
+
+  // Handle ExprList and ExprTuple
+  if ('elements' in exprAny && Array.isArray(exprAny.elements)) {
+    const inner = exprAny.elements.map((el: any) => renderValue(el)).join(', ')
+    return exprAny.cls === 'ExprTuple' ? `(${inner})` : `[${inner}]`
+  }
+
+  // Handle ExprDict
+  if (exprAny.cls === 'ExprDict' && Array.isArray(exprAny.keys) && Array.isArray(exprAny.values)) {
+    const pairs = exprAny.keys.map((k: any, i: number) =>
+      `${renderValue(k)}: ${renderValue(exprAny.values[i])}`
+    ).join(', ')
+    return `{${pairs}}`
+  }
+
+  // Handle ExprSubscript (like Dict[str, int])
+  if (exprAny.left && exprAny.slice) {
+    const left = renderValue(exprAny.left)
+    const slice = renderValue(exprAny.slice)
+    return `${left}[${slice}]`
+  }
+
+  // Handle slice expressions
+  if ('slice' in exprAny && exprAny.slice && !exprAny.left) {
+    return renderValue(exprAny.slice)
+  }
+
+  // Fallback for unknown expressions
+  if (typeof value === 'object') {
+    return JSON.stringify(value)
+  }
+
+  return String(value)
+}
+
+interface ModuleDocProps {
+  module: GriffeModule
+  /** URL prefix for links */
+  prefix?: string
+  /** Show full module content or just summary */
+  showFull?: boolean
+  /** Additional CSS class */
+  className?: string
+  /** Override display path (e.g., for aliases to show alias name instead of target path) */
+  displayPath?: string
+  /** GitHub repository URL for "Open in GitHub" links */
+  githubUrl?: string
+}
+
+/**
+ * Renders documentation for a module including its classes, functions, and submodules.
+ */
+export function ModuleDoc({ module, prefix = '/api', showFull = true, className = '', displayPath, githubUrl }: ModuleDocProps) {
+  const members = module.members ?? {}
+
+  // Separate members by type
+  const submodules: GriffeModule[] = []
+  const classes: GriffeClass[] = []
+  const functions: GriffeFunction[] = []
+  const attributes: GriffeAttribute[] = []
+
+  for (const member of Object.values(members)) {
+    switch (member.kind) {
+      case 'module':
+        submodules.push(member as GriffeModule)
+        break
+      case 'class':
+        classes.push(member as GriffeClass)
+        break
+      case 'function':
+        functions.push(member as GriffeFunction)
+        break
+      case 'attribute':
+        attributes.push(member as GriffeAttribute)
+        break
+    }
+  }
+
+  // Sort alphabetically
+  submodules.sort((a, b) => a.name.localeCompare(b.name))
+  classes.sort((a, b) => a.name.localeCompare(b.name))
+  functions.sort((a, b) => a.name.localeCompare(b.name))
+  attributes.sort((a, b) => a.name.localeCompare(b.name))
+
+  // Generate href for a member using dotted path
+  const memberHref = (member: GriffeMember) => {
+    const modulePath = module.path || module.name
+    return `${prefix}/${modulePath}.${member.name}`
+  }
+
+  return (
+    <div className={className}>
+      {/* Module header */}
+      <h1 id={module.name} className="text-3xl font-bold text-gray-900 dark:text-white mb-2">
+        <span className="text-gray-500 dark:text-gray-400 font-normal">module </span>
+        {displayPath || module.path || module.name}
+      </h1>
+
+      {/* Docstring */}
+      {module.docstring && (
+        <div className="mb-8">
+          <Docstring docstring={module.docstring} />
+        </div>
+      )}
+
+      {/* Submodules */}
+      {submodules.length > 0 && (
+        <div className="mb-8">
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-4 pb-2 border-b border-gray-200 dark:border-gray-700">
+            Submodules
+          </h2>
+          <ul className="grid grid-cols-1 md:grid-cols-2 gap-2">
+            {submodules.map((submodule) => (
+              <li key={submodule.name}>
+                <Link
+                  href={`${prefix}/${submodule.path || submodule.name}`}
+                  className="block p-3 rounded-lg border border-gray-200 dark:border-gray-700 hover:border-primary-300 dark:hover:border-primary-600 transition-colors"
+                >
+                  <div className="font-mono text-sm text-primary-600 dark:text-primary-400">
+                    {submodule.path || submodule.name}
+                  </div>
+                  {submodule.docstring && (
+                    <div className="text-sm text-gray-600 dark:text-gray-300 mt-1 line-clamp-2">
+                      {submodule.docstring.value.split('\n')[0]}
+                    </div>
+                  )}
+                </Link>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Classes - summary or full */}
+      {classes.length > 0 && (
+        <div id="classes" className="mb-8">
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-4 pb-2 border-b border-gray-200 dark:border-gray-700">
+            Classes
+          </h2>
+          {showFull ? (
+            <div className="space-y-12">
+              {classes.map((cls) => (
+                <ClassDoc key={cls.name} cls={cls} prefix={prefix} githubUrl={githubUrl} />
+              ))}
+            </div>
+          ) : (
+            <ul className="grid grid-cols-1 md:grid-cols-2 gap-2">
+              {classes.map((cls) => (
+                <li key={cls.name}>
+                  <Link
+                    href={memberHref(cls)}
+                    className="block p-3 rounded-lg border border-gray-200 dark:border-gray-700 hover:border-primary-300 dark:hover:border-primary-600 transition-colors"
+                  >
+                    <div className="font-mono text-sm text-primary-600 dark:text-primary-400">
+                      {cls.name}
+                    </div>
+                    {cls.docstring && (
+                      <div className="text-sm text-gray-600 dark:text-gray-300 mt-1 line-clamp-2">
+                        {cls.docstring.value.split('\n')[0]}
+                      </div>
+                    )}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+
+      {/* Functions - summary or full */}
+      {functions.length > 0 && (
+        <div id="functions" className="mb-8">
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-4 pb-2 border-b border-gray-200 dark:border-gray-700">
+            Functions
+          </h2>
+          {showFull ? (
+            <div className="space-y-8">
+              {functions.map((fn) => (
+                <FunctionDoc key={fn.name} fn={fn} githubUrl={githubUrl} />
+              ))}
+            </div>
+          ) : (
+            <ul className="grid grid-cols-1 md:grid-cols-2 gap-2">
+              {functions.map((fn) => (
+                <li key={fn.name}>
+                  <Link
+                    href={memberHref(fn)}
+                    className="block p-3 rounded-lg border border-gray-200 dark:border-gray-700 hover:border-primary-300 dark:hover:border-primary-600 transition-colors"
+                  >
+                    <div className="font-mono text-sm text-primary-600 dark:text-primary-400">
+                      {fn.name}()
+                    </div>
+                    {fn.docstring && (
+                      <div className="text-sm text-gray-600 dark:text-gray-300 mt-1 line-clamp-2">
+                        {fn.docstring.value.split('\n')[0]}
+                      </div>
+                    )}
+                  </Link>
+                </li>
+              ))}
+            </ul>
+          )}
+        </div>
+      )}
+
+      {/* Module-level attributes */}
+      {attributes.length > 0 && (
+        <div className="mb-8">
+          <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-4 pb-2 border-b border-gray-200 dark:border-gray-700">
+            Attributes
+          </h2>
+          <dl className="space-y-3">
+            {attributes.map((attr) => (
+              <div key={attr.name} id={attr.name} className="scroll-mt-20">
+                <dt className="font-mono text-sm">
+                  <span className="text-orange-600 dark:text-orange-400 font-semibold">{attr.name}</span>
+                  {attr.annotation && (
+                    <>
+                      <span className="text-gray-600 dark:text-gray-400">: </span>
+                      <span className="text-green-600 dark:text-green-400">
+                        {typeof attr.annotation === 'string' ? attr.annotation : attr.annotation.str || attr.annotation.name}
+                      </span>
+                    </>
+                  )}
+                  {attr.value && (
+                    <>
+                      <span className="text-gray-600 dark:text-gray-400"> = </span>
+                      <span className="text-cyan-600 dark:text-cyan-400">{renderValue(attr.value)}</span>
+                    </>
+                  )}
+                </dt>
+                {attr.docstring && (
+                  <dd className="mt-1 text-sm text-gray-600 dark:text-gray-300 ml-4">
+                    {attr.docstring.value}
+                  </dd>
+                )}
+              </div>
+            ))}
+          </dl>
+        </div>
+      )}
+
+      {/* Source location */}
+      {(module.relative_package_filepath || module.filepath) && (
+        <div className="mt-4 text-xs text-gray-500 dark:text-gray-400">
+          <span className="font-mono">{module.relative_package_filepath || module.filepath}</span>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/api/ParameterTable.tsx

@@ -0,0 +1,183 @@
+import type { GriffeParameter, GriffeDocstringSection, GriffeDocstringElement, GriffeExpression } from '../../types'
+import { CodeSpan } from './CodeSpan'
+
+/**
+ * Render a type annotation expression to string
+ */
+function renderExpression(expr: GriffeExpression | string | undefined): string {
+  if (!expr) return ''
+  if (typeof expr === 'string') return expr
+  if (expr.str) return expr.str
+  if (expr.canonical) return expr.canonical
+
+  const exprAny = expr as any
+
+  // Handle ExprName with member reference
+  if (expr.name && typeof expr.name === 'string') return expr.name
+
+  // Handle ExprBoolOp (like `config or StrawberryConfig()`)
+  if (exprAny.cls === 'ExprBoolOp' && exprAny.operator && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderExpression(v)).join(` ${exprAny.operator} `)
+  }
+
+  // Handle ExprBinOp (like `type | None`)
+  if (exprAny.cls === 'ExprBinOp' && exprAny.left && exprAny.right) {
+    const left = renderExpression(exprAny.left)
+    const right = renderExpression(exprAny.right)
+    const op = exprAny.operator || '|'
+    return `${left} ${op} ${right}`
+  }
+
+  // Handle ExprCall (like `StrawberryConfig()`)
+  if (exprAny.cls === 'ExprCall' && exprAny.function) {
+    const funcName = renderExpression(exprAny.function)
+    const args = Array.isArray(exprAny.arguments)
+      ? exprAny.arguments.map((a: any) => renderExpression(a)).join(', ')
+      : ''
+    return `${funcName}(${args})`
+  }
+
+  // Handle ExprAttribute (like contextlib.asynccontextmanager)
+  if (exprAny.cls === 'ExprAttribute' && Array.isArray(exprAny.values)) {
+    return exprAny.values.map((v: any) => renderExpression(v)).join('.')
+  }
+
+  // Handle ExprList and ExprTuple
+  if ('elements' in exprAny && Array.isArray(exprAny.elements)) {
+    const inner = exprAny.elements.map((el: any) => renderExpression(el)).join(', ')
+    return exprAny.cls === 'ExprTuple' ? `(${inner})` : `[${inner}]`
+  }
+
+  // Handle ExprDict
+  if (exprAny.cls === 'ExprDict' && Array.isArray(exprAny.keys) && Array.isArray(exprAny.values)) {
+    const pairs = exprAny.keys.map((k: any, i: number) =>
+      `${renderExpression(k)}: ${renderExpression(exprAny.values[i])}`
+    ).join(', ')
+    return `{${pairs}}`
+  }
+
+  // Handle ExprSubscript (like Dict[str, int])
+  if (exprAny.left && exprAny.slice) {
+    const left = renderExpression(exprAny.left)
+    const slice = renderExpression(exprAny.slice)
+    return `${left}[${slice}]`
+  }
+
+  // Handle slice expressions
+  if ('slice' in exprAny && exprAny.slice && !exprAny.left) {
+    return renderExpression(exprAny.slice)
+  }
+
+  // Fallback for unknown expressions
+  if (typeof expr === 'object') {
+    return JSON.stringify(expr)
+  }
+
+  return String(expr)
+}
+
+/**
+ * Get parameter description from docstring sections
+ */
+function getParamDescription(
+  paramName: string,
+  docstringSections?: GriffeDocstringSection[]
+): string | undefined {
+  if (!docstringSections) return undefined
+
+  for (const section of docstringSections) {
+    if (section.kind === 'parameters' && Array.isArray(section.value)) {
+      const param = (section.value as GriffeDocstringElement[]).find(
+        (p) => p.name === paramName
+      )
+      if (param) return param.description
+    }
+  }
+  return undefined
+}
+
+interface ParameterTableProps {
+  parameters: GriffeParameter[]
+  /** Docstring sections for parameter descriptions */
+  docstringSections?: GriffeDocstringSection[]
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Renders a two-column parameter list matching strawberry.rocks design.
+ * Left column: parameter name badge
+ * Right column: description, type, and default value
+ */
+export function ParameterTable({ parameters, docstringSections, className = '' }: ParameterTableProps) {
+  if (!parameters || parameters.length === 0) return null
+
+  // Filter out 'self' parameter for cleaner display
+  const displayParams = parameters.filter(p => p.name !== 'self')
+
+  if (displayParams.length === 0) return null
+
+  return (
+    <ol className={`list-none p-0 ${className}`}>
+      {displayParams.map((param, index) => {
+        const description = getParamDescription(param.name, docstringSections)
+        const annotation = renderExpression(param.annotation)
+        const defaultValue = renderExpression(param.default)
+        const isLast = index === displayParams.length - 1
+
+        return (
+          <li
+            key={param.name}
+            className="contents"
+          >
+            <div className={`grid grid-cols-[max-content_1fr] items-baseline gap-x-8 gap-y-2 py-6 ${!isLast ? 'border-b border-gray-200 dark:border-gray-700' : ''}`}>
+              {/* Parameter name badge - left column */}
+              <div className="flex-shrink-0">
+                <CodeSpan>
+                  {param.kind === 'var-positional' && '*'}
+                  {param.kind === 'var-keyword' && '**'}
+                  {param.name}:
+                </CodeSpan>
+              </div>
+
+              {/* Description and metadata - right column */}
+              <div className="space-y-3">
+                {/* Description */}
+                {description && (
+                  <p className="text-gray-700 dark:text-gray-300 leading-relaxed">
+                    {description}
+                  </p>
+                )}
+
+                {/* Type and Default in definition list style */}
+                <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-2">
+                  {annotation && (
+                    <>
+                      <dt className="font-semibold text-gray-500 dark:text-gray-400">
+                        Type
+                      </dt>
+                      <dd className="m-0">
+                        <CodeSpan>{annotation}</CodeSpan>
+                      </dd>
+                    </>
+                  )}
+
+                  {defaultValue && (
+                    <>
+                      <dt className="font-semibold text-gray-500 dark:text-gray-400">
+                        Default
+                      </dt>
+                      <dd className="m-0">
+                        <CodeSpan>{defaultValue}</CodeSpan>
+                      </dd>
+                    </>
+                  )}
+                </dl>
+              </div>
+            </div>
+          </li>
+        )
+      })}
+    </ol>
+  )
+}