dogsbay 0.2.0-beta.42 → 0.2.0-beta.44

package/dist/commands/migrate-mkdocs.js

@@ -77,6 +77,17 @@ export async function migrateMkdocs(source, options) {
         console.log("Pass --force to overwrite.");
         process.exit(1);
     }
+    // On a --force re-run the existing dogsbay.config.yml carries
+    // deployment config the user owns — site.url + site.basePath —
+    // that has NO other source: it isn't in mkdocs.yml, and --site-url
+    // is deliberately not inherited from the source. Read it so a
+    // re-run that omits the flags preserves those values instead of
+    // silently resetting site.url to unset and basePath to /docs.
+    // Explicit --site-url / --base-path flags still win; a fresh
+    // migration (no existing config) is unaffected.
+    const existingDeployment = existingConfig
+        ? readExistingDeployment(existingConfig)
+        : {};
     console.log();
     console.log(pc.bold(`Migrating MkDocs site to Dogsbay-MD: ${siteName}`));
     console.log(`Source:  ${sourceDir}`);
@@ -99,7 +110,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).
@@ -139,13 +158,18 @@ export async function migrateMkdocs(source, options) {
     // site.url is left unset and the build emits relative URLs.
     // sourceSiteUrl is kept only to warn the user it was dropped.
     const sourceSiteUrl = config.site_url || undefined;
-    const siteUrl = options.siteUrl || undefined;
+    // Precedence: --site-url flag → existing config (--force re-run) →
+    // unset. Never the source mkdocs.yml's site_url.
+    const siteUrl = options.siteUrl || existingDeployment.siteUrl || undefined;
     const repoUrl = config.repo_url || undefined;
-    // --base-path controls where docs sit under the host. Default
-    // /docs (matches every scaffolded dogsbay site); pass --base-path
-    // "" to serve at the host root — common for a dedicated repo or
-    // GitHub Pages project site.
-    const basePath = options.basePath !== undefined ? options.basePath : "/docs";
+    // --base-path controls where docs sit under the host. Precedence:
+    // --base-path flag → existing config (--force re-run) → /docs
+    // default (matches every scaffolded dogsbay site). Pass
+    // --base-path "" to serve at the host root — common for a
+    // dedicated repo or GitHub Pages project site.
+    const basePath = options.basePath !== undefined
+        ? options.basePath
+        : existingDeployment.basePath ?? "/docs";
     const siteDescription = config.site_description || undefined;
     const dogsbayConfig = {
         schemaVersion: 1,
@@ -163,9 +187,29 @@ 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`);
+    // Surface preserved deployment config so a --force re-run isn't a
+    // silent black box — the user sees what carried over.
+    if (!options.siteUrl && existingDeployment.siteUrl) {
+        console.log(pc.green(`Kept`) +
+            ` site.url from the existing config: ${existingDeployment.siteUrl}`);
+    }
+    if (options.basePath === undefined &&
+        existingDeployment.basePath !== undefined) {
+        console.log(pc.green(`Kept`) +
+            ` site.basePath from the existing config: "${existingDeployment.basePath}"`);
+    }
     if (sourceSiteUrl && !siteUrl) {
         console.log(pc.yellow(`Note:`) +
             ` source site_url (${sourceSiteUrl}) was not carried over —` +
@@ -304,8 +348,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 +505,84 @@ 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;
+}
+/**
+ * Read the user-owned deployment config — `site.url` + `site.basePath`
+ * — out of an existing `dogsbay.config.yml` so a `--force` re-run can
+ * preserve them when the `--site-url` / `--base-path` flags are
+ * omitted.
+ *
+ * Lenient on purpose: `YAML.parse` reads both .yml and .json (JSON is
+ * valid YAML), and an unparseable / unexpected-shape config falls
+ * through to `{}` rather than aborting the migration — a re-run
+ * should never be blocked by a stale config it's about to overwrite.
+ */
+function readExistingDeployment(configPath) {
+    try {
+        const parsed = YAML.parse(readFileSync(configPath, "utf-8"));
+        const site = parsed?.site;
+        return {
+            siteUrl: typeof site?.url === "string" ? site.url : undefined,
+            basePath: typeof site?.basePath === "string" ? site.basePath : undefined,
+        };
+    }
+    catch {
+        return {};
+    }
+}
 /**
  * Extract macros plugin data file mappings from mkdocs.yml.
  * Returns { varName: absolutePath } for each `include_yaml` entry,
@@ -850,7 +980,18 @@ function buildMigrationNotes(args) {
         }
         lines.push("Set the destination URL in `dogsbay.config.yml`:", "", "```yaml", "site:", "  url: https://you.github.io/your-repo   # drives sitemap, llms.txt, canonical", `  basePath: ${basePath || '""'}`, "```", "", "Or re-run the migration with `--site-url` (and optionally", "`--base-path`).", "");
     }
-    lines.push("## Re-running the migration", "", "If you find a regression and we ship a fix, re-run with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} --output ${outputDir} --force`, "```", "", "Note that `--force` overwrites all generated files; any hand edits", "to `./content/*.md` since the last migration will be lost. Commit", "your work first.", "");
+    // Re-run command — spell out the deployment flags so the
+    // documented command reproduces the same site.url / basePath even
+    // against a fresh output dir. (A bare `--force` re-run also
+    // preserves them now, read back from the existing config — see the
+    // note below — but a self-contained command is the safer thing to
+    // copy.)
+    const rerunFlags = ["--output", outputDir, "--force"];
+    if (siteUrl)
+        rerunFlags.push("--site-url", siteUrl);
+    if (basePath !== "/docs")
+        rerunFlags.push("--base-path", `"${basePath}"`);
+    lines.push("## Re-running the migration", "", "If you find a regression and a later release fixes it, re-run", "with `--force`:", "", "```bash", `npx dogsbay migrate-mkdocs ${sourceDir} ${rerunFlags.join(" ")}`, "```", "", "`--force` overwrites all generated files; any hand edits to", "`./content/*.md` since the last migration will be lost — commit", "your work first.", "", "Your deployment config is preserved across a re-run: `site.url`", "and `site.basePath` are read back from the existing", "`dogsbay.config.yml` when the `--site-url` / `--base-path` flags", "are omitted (the flags still win when passed). Everything else in", "the config is re-derived from the source `mkdocs.yml`.", "");
     if (lossy.length > 0) {
         lines.push("## Known limitations", "");
         lines.push("The following files have content that didn't fully round-trip", "into Dogsbay-MD. Review each one and fix manually:", "");

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.44",
   "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.44",
+    "@dogsbay/format-mkdocs": "0.2.0-beta.44",
+    "@dogsbay/format-astro": "0.2.0-beta.44",
+    "@dogsbay/format-obsidian": "0.2.0-beta.44",
+    "@dogsbay/format-mdx": "0.2.0-beta.44",
+    "@dogsbay/format-starlight": "0.2.0-beta.44",
+    "@dogsbay/format-dogsbay-md": "0.2.0-beta.44",
+    "@dogsbay/format-openapi": "0.2.0-beta.44",
+    "@dogsbay/types": "0.2.0-beta.44"
   },
   "devDependencies": {
     "@types/markdown-it": "^14.1.0",