dogsbay 0.2.0-beta.42 → 0.2.0-beta.43

package/dist/commands/migrate-mkdocs.js

@@ -99,7 +99,15 @@ export async function migrateMkdocs(source, options) {
     //    snippets, macros, autodoc, variants — see @dogsbay/format-
     //    mkdocs's CLAUDE.md) runs identically to import-mkdocs; only
     //    the final write target differs.
-    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config, { inlineAutodoc: options.inlineAutodoc ?? false });
+    // Lift the mkdocstrings Python handler options from mkdocs.yml.
+    // These become the project-level `autodoc.python` config block and
+    // also feed `--inline-autodoc`'s parser globalOptions — see
+    // plans/autodoc-mkdocstrings-options.md.
+    const autodocPythonOptions = extractAutodocOptions(config);
+    const { pageCount, lossy } = await collectAndWriteContent(sourceDir, fullDocsDir, outputDir, config, {
+        inlineAutodoc: options.inlineAutodoc ?? false,
+        autodocPythonOptions,
+    });
     console.log(pc.green(`Wrote`) + ` ${pageCount} pages to ./content/ as Dogsbay-MD`);
     // 3. Convert MkDocs nav: → ./content/nav.yml in canonical
     //    single-key-map shape (- Label: file.md / nested children).
@@ -163,6 +171,15 @@ export async function migrateMkdocs(source, options) {
             llmsTxt: true,
             mdMirror: true,
         },
+        // Project-level autodoc render options lifted from the source
+        // mkdocs.yml's mkdocstrings handler. resolve-autodoc applies
+        // these under per-directive props so migrated reference pages
+        // render with the same signature/member-order behaviour the
+        // MkDocs site configured. Omitted when the source declared no
+        // renderer-relevant options.
+        ...(autodocPythonOptions
+            ? { autodoc: { python: autodocPythonOptions } }
+            : {}),
     };
     writeFileSync(join(outputDir, "dogsbay.config.yml"), serializeConfig(dogsbayConfig, "yaml"));
     console.log(pc.green(`Wrote`) + ` dogsbay.config.yml`);
@@ -304,8 +321,16 @@ async function collectAndWriteContent(sourceDir, fullDocsDir, outputDir, mkdocsC
     if (opts.inlineAutodoc && autodocSourceRootAbs) {
         // Snapshot mode: resolve at migration time. The resolved api-*
         // TreeNodes serialize to Dogsbay-MD `:::api-*` directives via
-        // format-dogsbay-md's Phase 4a cases.
-        parseOpts.autodoc = { sourceRoot: autodocSourceRootAbs };
+        // format-dogsbay-md's Phase 4a cases. globalOptions carries the
+        // mkdocstrings handler options so the snapshot matches what the
+        // MkDocs site configured (members_order, merge_init_into_class,
+        // …) rather than the bare mkdocstrings defaults.
+        parseOpts.autodoc = {
+            sourceRoot: autodocSourceRootAbs,
+            ...(opts.autodocPythonOptions
+                ? { globalOptions: opts.autodocPythonOptions }
+                : {}),
+        };
     }
     // Preserve mode (default): no `autodoc` in parseOpts. The `:::`
     // paragraphs stay as raw text; we walk them in post-process and
@@ -453,6 +478,60 @@ function extractMkdocstringsConfig(mkdocsConfig) {
     }
     return null;
 }
+/**
+ * snake_case mkdocstrings handler option → camelCase Dogsbay
+ * `AutodocPythonOptions` key. Options the autodoc renderer doesn't
+ * understand (e.g. `extensions`, `preload_modules`,
+ * `docstring_section_style`) are intentionally absent — they fall
+ * through and are dropped. Mirrors the map in
+ * `format-mkdocs/src/importer.ts` so `migrate-mkdocs` and
+ * `import-mkdocs` honour the same handler options.
+ */
+const MKDOCSTRINGS_OPTION_MAP = {
+    show_source: "showSource",
+    show_bases: "showBases",
+    show_signature: "showSignature",
+    unwrap_annotated: "unwrapAnnotated",
+    group_by_category: "groupByCategory",
+    show_root_full_path: "showRootFullPath",
+    show_root_heading: "showRootHeading",
+    show_if_no_docstring: "showIfNoDocstring",
+    inherited_members: "inheritedMembers",
+    merge_init_into_class: "mergeInitIntoClass",
+    separate_signature: "separateSignature",
+    members_order: "membersOrder",
+    filters: "filters",
+    heading_level: "headingLevel",
+};
+/**
+ * Lift the mkdocstrings Python handler `options:` block out of
+ * mkdocs.yml and map it to `AutodocPythonOptions`.
+ *
+ * A MkDocs site configures the handler once; `import-mkdocs` threads
+ * those options into the autodoc renderer as `globalOptions`. Without
+ * this, migrated `:::autodoc` directives fall back to the bare
+ * mkdocstrings defaults (`merge_init_into_class: false`,
+ * `members_order: alphabetical`) — the reference pages lose the
+ * expanded constructor signature and the document-order member list.
+ *
+ * Returns null when mkdocstrings isn't declared or sets no
+ * renderer-relevant options. See plans/autodoc-mkdocstrings-options.md.
+ */
+function extractAutodocOptions(mkdocsConfig) {
+    const mkdocstrings = extractMkdocstringsConfig(mkdocsConfig);
+    if (!mkdocstrings)
+        return null;
+    const raw = mkdocstrings.handlers?.python?.options;
+    if (!raw || typeof raw !== "object")
+        return null;
+    const src = raw;
+    const out = {};
+    for (const [snake, camel] of Object.entries(MKDOCSTRINGS_OPTION_MAP)) {
+        if (src[snake] !== undefined)
+            out[camel] = src[snake];
+    }
+    return Object.keys(out).length > 0 ? out : null;
+}
 /**
  * Extract macros plugin data file mappings from mkdocs.yml.
  * Returns { varName: absolutePath } for each `include_yaml` entry,

package/dist/commands/site-build.js

@@ -176,6 +176,10 @@ export async function siteBuild(cwd, options) {
     const { resolveAutodocRefs } = await import("../resolve-autodoc.js");
     const autodocResult = await resolveAutodocRefs(pages, {
         configDir: dirname(configPath),
+        // Project-level autodoc render options (lifted from the source
+        // mkdocs.yml by migrate-mkdocs). Layered under per-directive
+        // props — see plans/autodoc-mkdocstrings-options.md.
+        pythonOptions: config.autodoc?.python,
     });
     if (autodocResult.resolved > 0 || autodocResult.failed > 0) {
         const parts = [];

package/dist/config/load.js

@@ -94,6 +94,7 @@ function validate(parsed, sourcePath) {
         throw new Error(`analytics must be an object in ${sourcePath}`);
     }
     const agent = validateAgent(obj.agent, sourcePath);
+    const autodoc = validateAutodoc(obj.autodoc, sourcePath);
     const taxonomies = validateTaxonomies(obj.taxonomies, sourcePath);
     const propSchema = validatePropSchema(obj.propSchema, sourcePath);
     const plugins = validatePlugins(obj.plugins, sourcePath);
@@ -108,11 +109,66 @@ function validate(parsed, sourcePath) {
         deploy: obj.deploy,
         analytics: obj.analytics,
         agent,
+        autodoc,
         taxonomies,
         propSchema,
         plugins,
     };
 }
+/**
+ * Validate the optional `autodoc:` block. One sub-block per language
+ * handler — only `python` exists today. Field names mirror
+ * `AutodocPythonOptions`; type-checked individually so a typo'd
+ * boolean doesn't silently flip a render default.
+ */
+function validateAutodoc(raw, sourcePath) {
+    if (raw === undefined)
+        return undefined;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new Error(`autodoc must be an object in ${sourcePath}`);
+    }
+    const a = raw;
+    if (a.python === undefined)
+        return {};
+    if (typeof a.python !== "object" || a.python === null || Array.isArray(a.python)) {
+        throw new Error(`autodoc.python must be an object in ${sourcePath}`);
+    }
+    const p = a.python;
+    const booleanKeys = [
+        "mergeInitIntoClass",
+        "separateSignature",
+        "unwrapAnnotated",
+        "inheritedMembers",
+        "showIfNoDocstring",
+        "showRootHeading",
+        "showRootFullPath",
+        "showBases",
+        "showSource",
+        "showSignature",
+        "groupByCategory",
+    ];
+    for (const key of booleanKeys) {
+        if (p[key] !== undefined && typeof p[key] !== "boolean") {
+            throw new Error(`autodoc.python.${key} must be a boolean in ${sourcePath}`);
+        }
+    }
+    if (p.membersOrder !== undefined &&
+        p.membersOrder !== "source" &&
+        p.membersOrder !== "alphabetical") {
+        throw new Error(`autodoc.python.membersOrder must be "source" or "alphabetical" ` +
+            `in ${sourcePath}; got ${JSON.stringify(p.membersOrder)}`);
+    }
+    if (p.headingLevel !== undefined && typeof p.headingLevel !== "number") {
+        throw new Error(`autodoc.python.headingLevel must be a number in ${sourcePath}`);
+    }
+    if (p.filters !== undefined) {
+        if (!Array.isArray(p.filters) ||
+            p.filters.some((f) => typeof f !== "string")) {
+            throw new Error(`autodoc.python.filters must be an array of strings in ${sourcePath}`);
+        }
+    }
+    return { python: p };
+}
 function validatePlugins(raw, sourcePath) {
     if (raw === undefined)
         return undefined;

package/dist/resolve-autodoc.js

@@ -75,6 +75,7 @@ export async function resolveAutodocRefs(pages, options) {
     for (const page of pages) {
         await walkAndResolve(page.tree, {
             configDir: options.configDir,
+            pythonOptions: options.pythonOptions,
             md,
             onResolved: () => {
                 resolved++;
@@ -187,16 +188,21 @@ async function resolveOne(node, ctx) {
     // Resolve against configDir so the resolver doesn't depend on
     // process.cwd().
     const sourceRoot = resolvePath(ctx.configDir, sourceRootRaw);
-    // Pull rendering options from props, layered on top of the
-    // mkdocstrings-compatible defaults. tree-builder.ts uses
-    // truthy-checks for several of these (e.g. `if (options.showSource
-    // && symbol.sourceText) { ... }`) — without the defaults the
-    // collapsible source-code block, attribute signatures, and class
-    // bases all silently drop. The defaults mirror format-mkdocs/
-    // src/loader.ts → processAutodocDirectives so the migrated
-    // output matches the legacy import-mkdocs output by default.
+    // Layer rendering options, lowest → highest precedence:
+    //   1. AUTODOC_RENDER_DEFAULTS — bare mkdocstrings defaults.
+    //      tree-builder.ts truthy-checks several of these, so without
+    //      them the collapsible source block, attribute signatures,
+    //      and class bases silently drop.
+    //   2. ctx.pythonOptions — project-level `config.autodoc.python`,
+    //      lifted by migrate-mkdocs from the source mkdocs.yml's
+    //      mkdocstrings handler (members_order, merge_init_into_class,
+    //      …). This is what makes a migrated reference page match the
+    //      original instead of the bare-defaults render.
+    //   3. props — the per-directive `:::autodoc` YAML body, so an
+    //      individual symbol can still override the project default.
     const renderOptions = {
         ...AUTODOC_RENDER_DEFAULTS,
+        ...(ctx.pythonOptions ?? {}),
         ...props,
     };
     delete renderOptions.ref;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dogsbay",
-  "version": "0.2.0-beta.42",
+  "version": "0.2.0-beta.43",
   "description": "CLI for Dogsbay — scaffold, build, and serve documentation sites with markdown / MkDocs / Obsidian / OpenAPI sources",
   "type": "module",
   "bin": {
@@ -32,15 +32,15 @@
     "picocolors": "^1.1.0",
     "prompts": "^2.4.2",
     "yaml": "^2.8.3",
-    "@dogsbay/autodoc-python": "0.2.0-beta.42",
-    "@dogsbay/format-mkdocs": "0.2.0-beta.42",
-    "@dogsbay/format-obsidian": "0.2.0-beta.42",
-    "@dogsbay/format-astro": "0.2.0-beta.42",
-    "@dogsbay/format-mdx": "0.2.0-beta.42",
-    "@dogsbay/format-starlight": "0.2.0-beta.42",
-    "@dogsbay/format-dogsbay-md": "0.2.0-beta.42",
-    "@dogsbay/format-openapi": "0.2.0-beta.42",
-    "@dogsbay/types": "0.2.0-beta.42"
+    "@dogsbay/autodoc-python": "0.2.0-beta.43",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.43",
+    "@dogsbay/format-astro": "0.2.0-beta.43",
+    "@dogsbay/format-obsidian": "0.2.0-beta.43",
+    "@dogsbay/format-mdx": "0.2.0-beta.43",
+    "@dogsbay/format-starlight": "0.2.0-beta.43",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.43",
+    "@dogsbay/format-openapi": "0.2.0-beta.43",
+    "@dogsbay/types": "0.2.0-beta.43"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",