feat: build each doc kind with its own MkDocs config and site
This commit is contained in:
@@ -2,8 +2,15 @@
|
||||
"module": "docforge.cli.commands",
|
||||
"content": {
|
||||
"path": "docforge.cli.commands",
|
||||
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---",
|
||||
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` each emit their own MkDocs config and\n build (`docs/mkdocs.{kind}.yml` into `site/{kind}`); `--mcp` generates a\n machine-readable bundle independently.\n\n---",
|
||||
"objects": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Path": {
|
||||
"name": "Path",
|
||||
"kind": "alias",
|
||||
@@ -245,15 +252,8 @@
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.mkdocs_utils",
|
||||
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'docforge.cli.mkdocs_utils.os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Iterable": {
|
||||
"name": "Iterable",
|
||||
"kind": "alias",
|
||||
@@ -275,6 +275,20 @@
|
||||
"signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs_utils.Path')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Any": {
|
||||
"name": "Any",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.Any",
|
||||
"signature": "<bound method Alias.signature of Alias('Any', 'docforge.cli.mkdocs_utils.Any')>",
|
||||
"docstring": null
|
||||
},
|
||||
"cast": {
|
||||
"name": "cast",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.cast",
|
||||
"signature": "<bound method Alias.signature of Alias('cast', 'docforge.cli.mkdocs_utils.cast')>",
|
||||
"docstring": null
|
||||
},
|
||||
"click": {
|
||||
"name": "click",
|
||||
"kind": "alias",
|
||||
@@ -393,19 +407,40 @@
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
|
||||
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
|
||||
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_lib_nav",
|
||||
"signature": "<bound method Alias.signature of Alias('build_lib_nav', 'docforge.cli.mkdocs_utils.build_lib_nav')>",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build",
|
||||
"signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
|
||||
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "<bound method Alias.signature of Alias('build_wiki_nav_block', 'docforge.cli.mkdocs_utils.build_wiki_nav_block')>",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.load_spec_icon",
|
||||
"signature": "<bound method Alias.signature of Alias('load_spec_icon', 'docforge.cli.mkdocs_utils.load_spec_icon')>",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_site_config",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_site_config', 'docforge.cli.mkdocs_utils.generate_site_config')>",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_configs",
|
||||
"signature": "<bound method Alias.signature of Alias('build_configs', 'docforge.cli.mkdocs_utils.build_configs')>",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
@@ -522,21 +557,21 @@
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 38, 260)>",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
|
||||
"signature": "<bound method Function.signature of Function('build', 40, 264)>",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 263, 324)>",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
|
||||
"signature": "<bound method Function.signature of Function('serve', 267, 367)>",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
|
||||
},
|
||||
"tree": {
|
||||
"name": "tree",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.tree",
|
||||
"signature": "<bound method Function.signature of Function('tree', 327, 363)>",
|
||||
"signature": "<bound method Function.signature of Function('tree', 370, 406)>",
|
||||
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
|
||||
},
|
||||
"Group": {
|
||||
|
||||
@@ -134,8 +134,15 @@
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` share a single MkDocs build; `--mcp`\n generates a machine-readable bundle independently.\n\n---",
|
||||
"docstring": "# Summary\n\nCommand definitions for the doc-forge CLI.\n\nProvides the CLI structure using Click, including build, serve, and tree commands.\n\n---\n\nNotes:\n - The `build` command validates requested modes before generating anything.\n - `--mkdocs`, `--api`, and `--wiki` each emit their own MkDocs config and\n build (`docs/mkdocs.{kind}.yml` into `site/{kind}`); `--mcp` generates a\n machine-readable bundle independently.\n\n---",
|
||||
"members": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Path": {
|
||||
"name": "Path",
|
||||
"kind": "alias",
|
||||
@@ -377,15 +384,8 @@
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.commands.mkdocs_utils",
|
||||
"signature": "<bound method Alias.signature of Alias('mkdocs_utils', 'docforge.cli.mkdocs_utils')>",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'docforge.cli.mkdocs_utils.os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Iterable": {
|
||||
"name": "Iterable",
|
||||
"kind": "alias",
|
||||
@@ -407,6 +407,20 @@
|
||||
"signature": "<bound method Alias.signature of Alias('Path', 'docforge.cli.mkdocs_utils.Path')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Any": {
|
||||
"name": "Any",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.Any",
|
||||
"signature": "<bound method Alias.signature of Alias('Any', 'docforge.cli.mkdocs_utils.Any')>",
|
||||
"docstring": null
|
||||
},
|
||||
"cast": {
|
||||
"name": "cast",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.cast",
|
||||
"signature": "<bound method Alias.signature of Alias('cast', 'docforge.cli.mkdocs_utils.cast')>",
|
||||
"docstring": null
|
||||
},
|
||||
"click": {
|
||||
"name": "click",
|
||||
"kind": "alias",
|
||||
@@ -525,19 +539,40 @@
|
||||
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.cli.mkdocs_utils.generate_sources')>",
|
||||
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_config', 'docforge.cli.mkdocs_utils.generate_config')>",
|
||||
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_lib_nav",
|
||||
"signature": "<bound method Alias.signature of Alias('build_lib_nav', 'docforge.cli.mkdocs_utils.build_lib_nav')>",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build",
|
||||
"signature": "<bound method Alias.signature of Alias('build', 'docforge.cli.mkdocs_utils.build')>",
|
||||
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "<bound method Alias.signature of Alias('build_wiki_nav_block', 'docforge.cli.mkdocs_utils.build_wiki_nav_block')>",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.load_spec_icon",
|
||||
"signature": "<bound method Alias.signature of Alias('load_spec_icon', 'docforge.cli.mkdocs_utils.load_spec_icon')>",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.generate_site_config",
|
||||
"signature": "<bound method Alias.signature of Alias('generate_site_config', 'docforge.cli.mkdocs_utils.generate_site_config')>",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.mkdocs_utils.build_configs",
|
||||
"signature": "<bound method Alias.signature of Alias('build_configs', 'docforge.cli.mkdocs_utils.build_configs')>",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
@@ -654,21 +689,21 @@
|
||||
"name": "build",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 38, 260)>",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds or serves the final output.\n\nDepending on the selected options, the build can target:\n\n- MkDocs static documentation sites for library reference docs\n- Swagger-enabled API docs generated from an OpenAPI spec\n- Hand-written wiki pages included in the MkDocs site\n- MCP structured documentation resources\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` are combined into a single MkDocs\n build, while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable MkDocs library documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Include a hand-written wiki directory in the MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the MkDocs site.\n\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n mkdocs_yml (Path):\n Output path for the generated MkDocs configuration.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
|
||||
"signature": "<bound method Function.signature of Function('build', 40, 264)>",
|
||||
"docstring": "Build documentation artifacts.\n\nThis command runs the full documentation pipeline: it loads Python\nmodules, generates renderer-specific documentation sources, and\noptionally builds the final output.\n\nDepending on the selected options, the build can target:\n\n- A lib MkDocs site (`--mkdocs`) for library reference docs\n- A swagger-enabled API MkDocs site (`--api`) built from an OpenAPI spec\n- A wiki MkDocs site (`--wiki`) built from hand-written markdown\n- MCP structured documentation resources (`--mcp`)\n\nEach enabled site kind produces its own MkDocs configuration\n(`docs/mkdocs.{kind}.yml`) and its own build (`site/{kind}`).\n\nNotes:\n - At least one of `--mcp`, `--mkdocs`, `--wiki`, or `--api` must be\n provided.\n - `--mkdocs`, `--api`, and `--wiki` emit independent MkDocs builds,\n while `--mcp` emits a machine-readable bundle.\n\nArgs:\n mcp (bool):\n Enable MCP documentation generation.\n\n mkdocs (bool):\n Enable the lib MkDocs documentation generation.\n\n api (bool):\n Enable API documentation generation from an OpenAPI spec.\n\n wiki (bool):\n Build a hand-written wiki directory as its own MkDocs site.\n\n module_is_source (bool):\n Treat the specified module directory as the project root.\n\n module (str | None):\n Python module import path to document.\n\n openapi_spec (Path | None):\n Path to the OpenAPI JSON specification used for API docs.\n\n project_name (str | None):\n Optional override for the project name.\n\n site_name (str | None):\n Display name for the lib and wiki MkDocs sites.\n\n docs_dir (Path):\n Shared documentation root used for generated sources.\n wiki_dir (Path):\n Directory containing hand-written wiki markdown files.\n\n nav_file (Path):\n Path to the navigation specification file.\n\n template (Path | None):\n Optional custom MkDocs configuration template.\n\n out_dir (Path):\n Output directory for generated MCP resources.\n\nRaises:\n click.UsageError:\n If required options are missing or conflicting."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 263, 324)>",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing documentation\n- An MCP server exposing structured documentation resources\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
|
||||
"signature": "<bound method Function.signature of Function('serve', 267, 367)>",
|
||||
"docstring": "Serve generated documentation locally.\n\nDepending on the selected mode, this command starts either:\n\n- A MkDocs development server for browsing a site, or\n- An MCP server exposing structured documentation resources\n\nThe kind flags (`--lib`, `--api`, `--wiki`) select the generated\nper-kind config (`docs/mkdocs.{kind}.yml`); `--mkdocs` serves the config\npassed via `--mkdocs-yml`.\n\nArgs:\n mcp (bool):\n Serve documentation using the MCP server.\n\n mkdocs (bool):\n Serve the MkDocs development site from ``--mkdocs-yml``.\n\n lib (bool):\n Serve the lib MkDocs site.\n\n api (bool):\n Serve the API MkDocs site.\n\n wiki (bool):\n Serve the wiki MkDocs site.\n\n module (str | None):\n Python module import path to serve via MCP.\n\n mkdocs_yml (Path):\n Path to the MkDocs configuration file.\n\n out_dir (Path):\n Root directory containing MCP documentation resources.\n\nRaises:\n click.UsageError:\n If invalid or conflicting options are provided."
|
||||
},
|
||||
"tree": {
|
||||
"name": "tree",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.commands.tree",
|
||||
"signature": "<bound method Function.signature of Function('tree', 327, 363)>",
|
||||
"signature": "<bound method Function.signature of Function('tree', 370, 406)>",
|
||||
"docstring": "Display the documentation object tree for a module.\n\nThis command introspects the specified module and prints a\nhierarchical representation of the discovered documentation\nobjects, including modules, classes, functions, and members.\n\nArgs:\n module (str):\n Python module import path to introspect.\n\n project_name (str | None):\n Optional name to display as the project root."
|
||||
},
|
||||
"Group": {
|
||||
@@ -805,15 +840,8 @@
|
||||
"kind": "module",
|
||||
"path": "docforge.cli.mkdocs_utils",
|
||||
"signature": null,
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"members": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Iterable": {
|
||||
"name": "Iterable",
|
||||
"kind": "alias",
|
||||
@@ -835,6 +863,20 @@
|
||||
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Any": {
|
||||
"name": "Any",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.Any",
|
||||
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
|
||||
"docstring": null
|
||||
},
|
||||
"cast": {
|
||||
"name": "cast",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.cast",
|
||||
"signature": "<bound method Alias.signature of Alias('cast', 'typing.cast')>",
|
||||
"docstring": null
|
||||
},
|
||||
"click": {
|
||||
"name": "click",
|
||||
"kind": "alias",
|
||||
@@ -950,28 +992,49 @@
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 34, 83)>",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 36, 85)>",
|
||||
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 86, 186)>",
|
||||
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
|
||||
"path": "docforge.cli.mkdocs_utils.build_lib_nav",
|
||||
"signature": "<bound method Function.signature of Function('build_lib_nav', 88, 121)>",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 313, 334)>",
|
||||
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
"path": "docforge.cli.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "<bound method Function.signature of Function('build_wiki_nav_block', 124, 147)>",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.load_spec_icon",
|
||||
"signature": "<bound method Function.signature of Function('load_spec_icon', 150, 169)>",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_site_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_site_config', 201, 282)>",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_configs",
|
||||
"signature": "<bound method Function.signature of Function('build_configs', 409, 430)>",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 337, 357)>",
|
||||
"signature": "<bound method Function.signature of Function('serve', 433, 453)>",
|
||||
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2,15 +2,8 @@
|
||||
"module": "docforge.cli.mkdocs_utils",
|
||||
"content": {
|
||||
"path": "docforge.cli.mkdocs_utils",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A single generated `mkdocs.yml` serves lib, api, and wiki content with\n merged navigation. Wiki navigation, when enabled, precedes every other\n group and its `index.md` becomes the site `Home`.\n\n---",
|
||||
"docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.\n\n---\n\nNotes:\n - A separate `mkdocs.{kind}.yml` configuration and build is emitted per\n enabled kind (lib, api, wiki), each scoped to its own `docs_dir` and\n written into its own `site_dir` (`site/lib`, `site/api`, `site/wiki`).\n - Navigation blocks are re-rooted per kind: the wiki navigation drops its\n leading `wiki/` scope and the resolved nav spec drops its `lib/` scope.\n\n---",
|
||||
"objects": {
|
||||
"os": {
|
||||
"name": "os",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.os",
|
||||
"signature": "<bound method Alias.signature of Alias('os', 'os')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Iterable": {
|
||||
"name": "Iterable",
|
||||
"kind": "alias",
|
||||
@@ -32,6 +25,20 @@
|
||||
"signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
|
||||
"docstring": null
|
||||
},
|
||||
"Any": {
|
||||
"name": "Any",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.Any",
|
||||
"signature": "<bound method Alias.signature of Alias('Any', 'typing.Any')>",
|
||||
"docstring": null
|
||||
},
|
||||
"cast": {
|
||||
"name": "cast",
|
||||
"kind": "alias",
|
||||
"path": "docforge.cli.mkdocs_utils.cast",
|
||||
"signature": "<bound method Alias.signature of Alias('cast', 'typing.cast')>",
|
||||
"docstring": null
|
||||
},
|
||||
"click": {
|
||||
"name": "click",
|
||||
"kind": "alias",
|
||||
@@ -147,28 +154,49 @@
|
||||
"name": "generate_sources",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_sources",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 34, 83)>",
|
||||
"signature": "<bound method Function.signature of Function('generate_sources', 36, 85)>",
|
||||
"docstring": "Generate MkDocs Markdown sources for a Python module.\n\nThis function introspects the specified module, builds the internal\ndocumentation model, and renders Markdown documentation files for\nuse with MkDocs.\n\nArgs:\n module (str):\n Python module import path used as the entry point for\n documentation generation.\n\n docs_dir (Path):\n Directory where the generated Markdown files will be written.\n\n project_name (str | None):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (bool | None):\n If True, treat the specified module directory as the project root\n rather than a nested module.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written. If not\n provided, defaults to the parent of ``docs_dir``."
|
||||
},
|
||||
"generate_config": {
|
||||
"name": "generate_config",
|
||||
"build_lib_nav": {
|
||||
"name": "build_lib_nav",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_config', 86, 186)>",
|
||||
"docstring": "Generate an `mkdocs.yml` configuration file.\n\nThe configuration is created by combining a template configuration\nwith a navigation structure derived from the docforge navigation\nspecification (and, when a wiki directory is provided, from the wiki\nfile structure).\n\nThe ``docs_dir`` is always written relative to the MkDocs root and is\nexpected to be the shared documentation parent (for example ``docs``),\nwith generated sources nested under ``lib/`` or ``api/`` subdirectories\nand hand-written wiki content under a ``wiki/`` subdirectory.\n\nArgs:\n docs_dir (Path):\n Shared documentation root used as the MkDocs ``docs_dir``.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template.\n If not provided, built-in templates are merged; the provided\n template replaces the built-in templates entirely.\n\n out (Path):\n Destination path where the generated `mkdocs.yml` file will be written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n modes (Iterable[str] | None):\n Documentation modes to enable. Each mode contributes its own\n built-in template fragment (for example ``lib``, ``api``, or\n ``wiki``), merged on top of the shared ``mkdocs.common.yml``\n template.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n wiki_dir (Path | None):\n Optional path to a hand-written wiki directory (for example\n ``docs/wiki``). When provided, the site navigation is derived\n from the wiki file structure and placed before the navigation\n groups defined in ``nav_file``.\n\nRaises:\n click.FileError:\n If the navigation specification, template, or wiki directory\n cannot be found."
|
||||
"path": "docforge.cli.mkdocs_utils.build_lib_nav",
|
||||
"signature": "<bound method Function.signature of Function('build_lib_nav', 88, 121)>",
|
||||
"docstring": "Build the re-rooted navigation block for a lib site.\n\nThe navigation specification is resolved against the shared documentation\nroot and every resulting path is re-rooted relative to the ``lib``\nsubdirectory by stripping its leading ``lib/`` scope component.\n\nArgs:\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n docs_root (Path):\n Shared documentation root containing the ``lib`` sources.\n\nReturns:\n tuple[list[dict[str, Any]], dict[str, str] | None]:\n The re-rooted navigation block and the optional theme icon\n mapping from the specification.\n\nRaises:\n click.FileError:\n If the navigation specification cannot be found."
|
||||
},
|
||||
"build": {
|
||||
"name": "build",
|
||||
"build_wiki_nav_block": {
|
||||
"name": "build_wiki_nav_block",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build",
|
||||
"signature": "<bound method Function.signature of Function('build', 313, 334)>",
|
||||
"docstring": "Build the MkDocs documentation site.\n\nThis function loads the MkDocs configuration and runs the MkDocs\nbuild command to generate the final static documentation site.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
"path": "docforge.cli.mkdocs_utils.build_wiki_nav_block",
|
||||
"signature": "<bound method Function.signature of Function('build_wiki_nav_block', 124, 147)>",
|
||||
"docstring": "Build the re-rooted navigation block for a wiki site.\n\nThe wiki navigation derived from the wiki file structure is re-rooted\nrelative to the wiki directory itself by stripping the leading ``wiki/``\nscope component.\n\nArgs:\n wiki_dir (Path):\n Path to the hand-written wiki directory, for example ``docs/wiki``.\n\nReturns:\n list[dict[str, Any]]:\n Navigation entries relative to the wiki directory.\n\nRaises:\n click.FileError:\n If the wiki directory does not exist."
|
||||
},
|
||||
"load_spec_icon": {
|
||||
"name": "load_spec_icon",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.load_spec_icon",
|
||||
"signature": "<bound method Function.signature of Function('load_spec_icon', 150, 169)>",
|
||||
"docstring": "Load the theme icon mapping from a navigation specification.\n\nArgs:\n nav_file (Path):\n Path to the navigation specification file.\n\nReturns:\n dict[str, str] | None:\n The icon mapping, or ``None`` when the specification file is\n absent or cannot be parsed."
|
||||
},
|
||||
"generate_site_config": {
|
||||
"name": "generate_site_config",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.generate_site_config",
|
||||
"signature": "<bound method Function.signature of Function('generate_site_config', 201, 282)>",
|
||||
"docstring": "Generate a per-kind `mkdocs.{kind}.yml` configuration file.\n\nThe configuration is created by merging the shared ``mkdocs.common.yml``\ntemplate with the fragment contributed by the kind (``lib``, ``api``, or\n``wiki``). Both ``docs_dir`` and ``site_dir`` are written relative to the\nconfiguration file's directory: the kind's sources when expressed as a\nsibling path (for example ``lib``) and the per-kind site output (for\nexample ``../site/lib``).\n\nArgs:\n kind (str):\n Documentation kind, one of ``lib``, ``api``, or ``wiki``.\n\n kind_root (Path):\n Directory scoped to the kind (for example ``docs/lib``) that\n serves as the MkDocs ``docs_dir``.\n\n nav_block (list[dict[str, Any]]):\n Re-rooted navigation entries for the kind's site.\n\n out (Path):\n Destination path where the generated ``mkdocs.{kind}.yml`` file\n is written.\n\n site_name (str):\n Display name for the generated documentation site.\n\n docs_dir (str):\n MkDocs ``docs_dir`` value, relative to the configuration\n file's directory.\n\n site_dir (str):\n MkDocs ``site_dir`` value, relative to the configuration\n file's directory.\n\n template (Path | None):\n Optional path to a fully custom MkDocs configuration template\n that replaces the built-in templates entirely.\n\n site_description (str | None):\n Optional site description written into the configuration.\n\n site_author (str | None):\n Optional site author written into the configuration.\n\n theme_icon (dict[str, str] | None):\n Optional mapping of theme icon entries injected as\n ``theme.icon``."
|
||||
},
|
||||
"build_configs": {
|
||||
"name": "build_configs",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.build_configs",
|
||||
"signature": "<bound method Function.signature of Function('build_configs', 409, 430)>",
|
||||
"docstring": "Build the MkDocs documentation site for every given configuration.\n\nEach configuration file is loaded and built in turn, producing the\nper-kind static sites (``site/lib``, ``site/api``, ``site/wiki``).\n\nArgs:\n yml_paths (Iterable[Path]):\n Configuration files to build, in order.\n\nRaises:\n click.ClickException:\n If a configuration file does not exist."
|
||||
},
|
||||
"serve": {
|
||||
"name": "serve",
|
||||
"kind": "function",
|
||||
"path": "docforge.cli.mkdocs_utils.serve",
|
||||
"signature": "<bound method Function.signature of Function('serve', 337, 357)>",
|
||||
"signature": "<bound method Function.signature of Function('serve', 433, 453)>",
|
||||
"docstring": "Start an MkDocs development server with live reload.\n\nThe server watches documentation files and automatically reloads\nthe site when changes are detected.\n\nArgs:\n mkdocs_yml (Path):\n Path to the `mkdocs.yml` configuration file.\n\nRaises:\n click.ClickException:\n If the configuration file does not exist."
|
||||
}
|
||||
}
|
||||
|
||||
File diff suppressed because one or more lines are too long
98
docs/mkdocs.lib.yml
Normal file
98
docs/mkdocs.lib.yml
Normal file
@@ -0,0 +1,98 @@
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
- scheme: slate
|
||||
primary: deep purple
|
||||
accent: cyan
|
||||
font:
|
||||
text: Inter
|
||||
code: JetBrains Mono
|
||||
features:
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.indexes
|
||||
- content.code.copy
|
||||
- content.code.annotate
|
||||
- content.tabs.link
|
||||
- content.action.edit
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
icon:
|
||||
logo: material/file-document-multiple
|
||||
repo: fontawesome/brands/github
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- tables
|
||||
- footnotes
|
||||
- pymdownx.caret
|
||||
- pymdownx.tilde
|
||||
- pymdownx.mark
|
||||
extra_css:
|
||||
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
|
||||
plugins:
|
||||
- search
|
||||
- mkdocstrings:
|
||||
handlers:
|
||||
python:
|
||||
paths:
|
||||
- .
|
||||
options:
|
||||
docstring_style: google
|
||||
show_source: false
|
||||
show_signature_annotations: true
|
||||
separate_signature: true
|
||||
merge_init_into_class: true
|
||||
inherited_members: true
|
||||
annotations_path: brief
|
||||
show_root_heading: true
|
||||
group_by_category: true
|
||||
show_category_heading: true
|
||||
show_object_full_path: false
|
||||
show_symbol_type_heading: true
|
||||
site_name: docforge
|
||||
docs_dir: lib
|
||||
site_dir: ../site/lib
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Loaders:
|
||||
- loaders/index.md
|
||||
- loaders/griffe_loader.md
|
||||
- Models:
|
||||
- models/index.md
|
||||
- models/module.md
|
||||
- models/object.md
|
||||
- models/project.md
|
||||
- Navigation:
|
||||
- nav/index.md
|
||||
- nav/spec.md
|
||||
- nav/resolver.md
|
||||
- nav/mkdocs.md
|
||||
- Renderers:
|
||||
- renderers/index.md
|
||||
- renderers/base.md
|
||||
- renderers/mkdocs_renderer.md
|
||||
- renderers/mcp_renderer.md
|
||||
- CLI:
|
||||
- cli/index.md
|
||||
- cli/main.md
|
||||
- cli/commands.md
|
||||
- cli/api_utils.md
|
||||
- cli/mcp_utils.md
|
||||
- cli/mkdocs_utils.md
|
||||
64
docs/mkdocs.wiki.yml
Normal file
64
docs/mkdocs.wiki.yml
Normal file
@@ -0,0 +1,64 @@
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
- scheme: slate
|
||||
primary: deep purple
|
||||
accent: cyan
|
||||
font:
|
||||
text: Inter
|
||||
code: JetBrains Mono
|
||||
features:
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.indexes
|
||||
- content.code.copy
|
||||
- content.code.annotate
|
||||
- content.tabs.link
|
||||
- content.action.edit
|
||||
- search.highlight
|
||||
- search.share
|
||||
- search.suggest
|
||||
icon:
|
||||
logo: material/file-document-multiple
|
||||
repo: fontawesome/brands/github
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- pymdownx.highlight:
|
||||
linenums: true
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- tables
|
||||
- footnotes
|
||||
- pymdownx.caret
|
||||
- pymdownx.tilde
|
||||
- pymdownx.mark
|
||||
extra_css:
|
||||
- https://unpkg.com/dracula-prism/dist/css/dracula-prism.css
|
||||
plugins:
|
||||
- search
|
||||
site_name: docforge
|
||||
docs_dir: wiki
|
||||
site_dir: ../site/wiki
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Overview: 01_overview.md
|
||||
- Architecture: 02_architecture.md
|
||||
- Conventions: 03_conventions.md
|
||||
- Iterative Workflow: 04_iterative_workflow.md
|
||||
- Development:
|
||||
- Environment: 05_development/01_environment.md
|
||||
- Quality Gates: 05_development/02_quality_gates.md
|
||||
- Gsdfc Guide: 05_development/03_gsdfc_guide.md
|
||||
- Mcp Guide: 05_development/04_mcp_guide.md
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
`docforge` turns GSDFC-compliant Python docstrings into maintainable reference
|
||||
documentation. It never edits source docstrings; it reads them, renders them,
|
||||
and assembles a single MkDocs site from all available material.
|
||||
and assembles documentation sites from all available material.
|
||||
|
||||
## What it generates
|
||||
|
||||
@@ -13,16 +13,17 @@ and assembles a single MkDocs site from all available material.
|
||||
| `wiki` | Hand-written markdown | `docs/wiki/**` (unchanged) |
|
||||
| `mcp` | GSDFC docstrings + renderers | `docs/mcp/**` structured JSON |
|
||||
|
||||
## Combined build
|
||||
## Per-kind MkDocs builds
|
||||
|
||||
One `mkdocs.yml` and one MkDocs build serve all kinds:
|
||||
Each enabled site kind produces its own MkDocs configuration and build:
|
||||
|
||||
1. Wiki navigation is derived from the `docs/wiki/` file structure.
|
||||
2. Generated library/API navigation is appended after it.
|
||||
3. The wiki `index.md` becomes the site `Home`.
|
||||
1. `--mkdocs` (lib) writes `docs/mkdocs.lib.yml` and builds `site/lib/`.
|
||||
2. `--api` writes `docs/mkdocs.api.yml` and builds `site/api/`.
|
||||
3. `--wiki` writes `docs/mkdocs.wiki.yml` and builds `site/wiki/`.
|
||||
|
||||
Hand-written wiki content is never overwritten or regenerated — only its
|
||||
navigation is derived automatically.
|
||||
Every site is self-contained (own theme assets and search index) with
|
||||
navigation derived or scoped to that kind. Hand-written wiki content is never
|
||||
overwritten or regenerated — only its navigation is derived automatically.
|
||||
|
||||
## MCP bundle
|
||||
|
||||
|
||||
@@ -35,6 +35,6 @@ file structure via `build_wiki_nav`.
|
||||
|
||||
- `commands.py` — the `build` command and its `--mkdocs` / `--api` / `--wiki`
|
||||
/ `--mcp` modes
|
||||
- `mkdocs_utils.py` — config generation (`mkdocs.yml`) including merged
|
||||
wiki + lib + api navigation
|
||||
- `mkdocs_utils.py` — per-kind config generation (`docs/mkdocs.{lib,api,wiki}.yml`)
|
||||
with navigation re-rooted to each kind's `docs_dir`
|
||||
- `api_utils.py` — OpenAPI loading and API docs generation
|
||||
@@ -8,7 +8,7 @@ A docs build runs through the CLI in a single pass.
|
||||
# Library reference only
|
||||
doc-forge build --mkdocs --module docforge
|
||||
|
||||
# Wiki + library combined (single MkDocs build)
|
||||
# Wiki + library (each an independent MkDocs build)
|
||||
doc-forge build --wiki --mkdocs --module docforge
|
||||
|
||||
# Wiki only — no module required
|
||||
@@ -18,21 +18,26 @@ doc-forge build --wiki --site-name docforge
|
||||
doc-forge build --mcp --module docforge
|
||||
```
|
||||
|
||||
## What a combined build does
|
||||
## What a build does
|
||||
|
||||
1. Validates the requested modes (`--mkdocs`, `--api`, `--wiki`, `--mcp`).
|
||||
2. Generates library sources under `docs/lib/**` with `MkDocsRenderer`.
|
||||
3. Generates API sources under `docs/api/**` when `--api` is given.
|
||||
4. Derives wiki navigation from `docs/wiki/**`.
|
||||
5. Writes `mkdocs.yml` with merged navigation — wiki first, generated groups
|
||||
appended, and the wiki `Home` replacing any spec `Home` entry.
|
||||
6. Runs `mkdocs build` once and emits the site.
|
||||
4. Derives the wiki navigation from `docs/wiki/**`.
|
||||
5. Writes one MkDocs config per site kind (`docs/mkdocs.{lib,api,wiki}.yml`),
|
||||
re-rooting navigation paths to each kind's `docs_dir`.
|
||||
6. Runs `mkdocs build` once per config, emitting self-contained sites
|
||||
`site/lib/`, `site/api/`, and `site/wiki/`.
|
||||
|
||||
## Explore the site
|
||||
## Explore the sites
|
||||
|
||||
```bash
|
||||
doc-forge build --wiki --mkdocs --module docforge
|
||||
doc-forge serve --mkdocs --mkdocs-yml mkdocs.yml
|
||||
doc-forge serve --wiki # serves site preview from docs/mkdocs.wiki.yml
|
||||
doc-forge serve --lib
|
||||
doc-forge serve --api
|
||||
# or target any config directly:
|
||||
doc-forge serve --mkdocs --mkdocs-yml docs/mkdocs.wiki.yml
|
||||
```
|
||||
|
||||
## Serve the MCP bundle
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
`docforge` is an internal documentation tool that generates reference
|
||||
documentation from Google-Styled Doc-Forge Convention (GSDFC) docstrings and
|
||||
assembles it into a single MkDocs site, alongside hand-written wiki pages and
|
||||
assembles it into per-kind MkDocs sites, alongside hand-written wiki pages and
|
||||
OpenAPI-based API docs.
|
||||
|
||||
---
|
||||
@@ -11,7 +11,7 @@ OpenAPI-based API docs.
|
||||
|
||||
- 🧪 GSDFC docstring extraction via Griffe
|
||||
- 🧭 Auto-derived navigation for hand-written wiki pages
|
||||
- 🗂 Combined MkDocs build: wiki first, then generated library/API reference
|
||||
- 🗂 Independent MkDocs builds per kind (lib, api, wiki) into `site/{kind}`
|
||||
- 🔌 Material MkDocs theming out of the box
|
||||
- 📦 MCP structured documentation resources
|
||||
|
||||
|
||||
Reference in New Issue
Block a user