feat: build each doc kind with its own MkDocs config and site
This commit is contained in:
@@ -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."
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user