204 lines
20 KiB
JSON
204 lines
20 KiB
JSON
{
|
|
"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 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": {
|
|
"Iterable": {
|
|
"name": "Iterable",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.mkdocs_utils.Iterable",
|
|
"signature": "<bound method Alias.signature of Alias('Iterable', 'collections.abc.Iterable')>",
|
|
"docstring": null
|
|
},
|
|
"resources": {
|
|
"name": "resources",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.mkdocs_utils.resources",
|
|
"signature": "<bound method Alias.signature of Alias('resources', 'importlib.resources')>",
|
|
"docstring": null
|
|
},
|
|
"Path": {
|
|
"name": "Path",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.mkdocs_utils.Path",
|
|
"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",
|
|
"path": "docforge.cli.mkdocs_utils.click",
|
|
"signature": "<bound method Alias.signature of Alias('click', 'click')>",
|
|
"docstring": null
|
|
},
|
|
"yaml": {
|
|
"name": "yaml",
|
|
"kind": "alias",
|
|
"path": "docforge.cli.mkdocs_utils.yaml",
|
|
"signature": "<bound method Alias.signature of Alias('yaml', 'yaml')>",
|
|
"docstring": null
|
|
},
|
|
"GriffeLoader": {
|
|
"name": "GriffeLoader",
|
|
"kind": "class",
|
|
"path": "docforge.cli.mkdocs_utils.GriffeLoader",
|
|
"signature": "<bound method Alias.signature of Alias('GriffeLoader', 'docforge.loaders.GriffeLoader')>",
|
|
"docstring": "Load Python modules using Griffe and convert them into doc-forge models.\n\nThis loader uses the Griffe introspection engine to analyze Python source\ncode and transform the extracted information into `Project`, `Module`,\nand `DocObject` instances used by doc-forge.\n\nAttributes:\n _loader (_GriffeLoader):\n Internal Griffe loader with dedicated module and line collections.",
|
|
"members": {
|
|
"load_project": {
|
|
"name": "load_project",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project",
|
|
"signature": "<bound method Alias.signature of Alias('load_project', 'docforge.loaders.griffe_loader.GriffeLoader.load_project')>",
|
|
"docstring": "Load multiple modules and assemble them into a Project model.\n\nEach module path is introspected and converted into a `Module`\ninstance. All modules are then aggregated into a single `Project`\nobject.\n\nArgs:\n module_paths (list[str]):\n List of dotted module import paths to load.\n\n project_name (str | None):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool | None):\n If True, modules that fail to load will be skipped instead of raising an error.\n\nReturns:\n Project:\n A populated `Project` instance containing the loaded modules.\n\nRaises:\n ValueError:\n If no module paths are provided.\n\n ImportError:\n If a module fails to load and `skip_import_errors` is False."
|
|
},
|
|
"load_module": {
|
|
"name": "load_module",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.GriffeLoader.load_module",
|
|
"signature": "<bound method Alias.signature of Alias('load_module', 'docforge.loaders.griffe_loader.GriffeLoader.load_module')>",
|
|
"docstring": "Load and convert a single Python module.\n\nThe module is introspected using Griffe and then transformed into\na doc-forge `Module` model.\n\nArgs:\n path (str):\n Dotted import path of the module.\n\nReturns:\n Module:\n A populated `Module` instance.\n\nRaises:\n ImportError:\n If the module cannot be loaded by Griffe.\n\n KeyError:\n If the loaded module is missing from the module collection.\n\nExample:\n Load a single module:\n\n ```python\n loader = GriffeLoader()\n module = loader.load_module(\"mypackage.submodule\")\n ```"
|
|
}
|
|
}
|
|
},
|
|
"discover_module_paths": {
|
|
"name": "discover_module_paths",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.discover_module_paths",
|
|
"signature": "<bound method Alias.signature of Alias('discover_module_paths', 'docforge.loaders.discover_module_paths')>",
|
|
"docstring": "Discover Python modules within a package directory.\n\nThe function scans the filesystem for `.py` files inside the specified\npackage and converts them into dotted module import paths.\n\nDiscovery rules:\n\n- Directories containing `__init__.py` are treated as packages.\n- Each `.py` file is treated as a module.\n- Results are returned as dotted import paths.\n\nArgs:\n module_name (str):\n Top-level package name to discover modules from.\n\n project_root (Path | None):\n Root directory used to resolve module paths. If not provided, the\n current working directory is used.\n\nReturns:\n list[str]:\n A sorted list of unique dotted module import paths.\n\nRaises:\n FileNotFoundError:\n If the specified package directory does not exist."
|
|
},
|
|
"MkDocsNavEmitter": {
|
|
"name": "MkDocsNavEmitter",
|
|
"kind": "class",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter",
|
|
"signature": "<bound method Alias.signature of Alias('MkDocsNavEmitter', 'docforge.nav.MkDocsNavEmitter')>",
|
|
"docstring": "Emit MkDocs navigation structures from resolved navigation data.\n\nThe emitter transforms a ``ResolvedNav`` object into the YAML-compatible\nlist structure expected by the MkDocs ``nav`` configuration field.",
|
|
"members": {
|
|
"emit": {
|
|
"name": "emit",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter.emit",
|
|
"signature": "<bound method Alias.signature of Alias('emit', 'docforge.nav.mkdocs.MkDocsNavEmitter.emit')>",
|
|
"docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav (ResolvedNav):\n Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\n list[dict[str, Any]]:\n A list of dictionaries representing the MkDocs navigation layout.\n Each dictionary maps a navigation label to a page or a list of\n pages."
|
|
}
|
|
}
|
|
},
|
|
"build_wiki_nav": {
|
|
"name": "build_wiki_nav",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.build_wiki_nav",
|
|
"signature": "<bound method Alias.signature of Alias('build_wiki_nav', 'docforge.nav.build_wiki_nav')>",
|
|
"docstring": "Derive an MkDocs navigation block from a wiki directory.\n\nReturned paths are relative to the parent of ``wiki_dir`` and carry the\nwiki directory name as their leading component (for example\n``wiki/01_overview.md`` when the wiki lives at ``docs/wiki``). This makes\nthe result directly usable in an MkDocs ``nav`` block with\n\n- ``index.md`` at the wiki root becomes the ``Home`` entry.\n- Page labels are derived from filenames: numeric order prefixes such as\n ``01_`` or ``02-`` are stripped, separators are replaced with spaces, and\n names are title-cased (``01_overview.md`` becomes ``Overview``).\n- Subdirectories become nested navigation groups. A nested ``index.md`` is\n rendered as the section root placed first inside the group.\n- Only ``.md`` files are considered; hidden entries are ignored.\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 compatible with the MkDocs ``nav`` configuration.\n The list is empty if the wiki contains no Markdown files.\n\nRaises:\n FileNotFoundError:\n If the wiki directory does not exist."
|
|
},
|
|
"load_nav_spec": {
|
|
"name": "load_nav_spec",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.load_nav_spec",
|
|
"signature": "<bound method Alias.signature of Alias('load_nav_spec', 'docforge.nav.load_nav_spec')>",
|
|
"docstring": "Load a navigation specification file.\n\nThis helper function reads a YAML navigation file and constructs a\ncorresponding ``NavSpec`` instance.\n\nArgs:\n path (Path):\n Path to the navigation specification file.\n\nReturns:\n NavSpec:\n A ``NavSpec`` instance representing the parsed specification.\n\nRaises:\n FileNotFoundError: If the specification file does not exist.\n ValueError: If the YAML structure is invalid."
|
|
},
|
|
"resolve_nav": {
|
|
"name": "resolve_nav",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.resolve_nav",
|
|
"signature": "<bound method Alias.signature of Alias('resolve_nav', 'docforge.nav.resolve_nav')>",
|
|
"docstring": "Resolve a navigation specification against the filesystem.\n\nThe function expands glob patterns defined in a ``NavSpec`` and verifies\nthat referenced documentation files exist within the documentation root.\n\nArgs:\n spec (NavSpec):\n Navigation specification describing documentation layout.\n docs_root (Path):\n Root directory containing documentation Markdown files.\n\nReturns:\n ResolvedNav:\n A `ResolvedNav` instance containing validated navigation paths.\n\nRaises:\n FileNotFoundError: If the documentation root does not exist or a\n navigation pattern does not match any files."
|
|
},
|
|
"MkDocsRenderer": {
|
|
"name": "MkDocsRenderer",
|
|
"kind": "class",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer",
|
|
"signature": "<bound method Alias.signature of Alias('MkDocsRenderer', 'docforge.renderers.MkDocsRenderer')>",
|
|
"docstring": "Renderer that produces Markdown documentation for MkDocs.\n\nGenerated pages use mkdocstrings directives to reference Python modules,\nallowing MkDocs to render API documentation dynamically.",
|
|
"members": {
|
|
"name": {
|
|
"name": "name",
|
|
"kind": "attribute",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.name",
|
|
"signature": "<bound method Alias.signature of Alias('name', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.name')>",
|
|
"docstring": null
|
|
},
|
|
"generate_sources": {
|
|
"name": "generate_sources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources",
|
|
"signature": "<bound method Alias.signature of Alias('generate_sources', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources')>",
|
|
"docstring": "Generate Markdown documentation files for a project.\n\nThis method renders a documentation structure from the provided\nproject model and writes the resulting Markdown files to the\nspecified output directory.\n\nArgs:\n project (Project):\n Project model containing modules to document.\n\n out_dir (Path):\n Directory where generated Markdown files will be written.\n\n module_is_source (bool | None):\n If True, treat the specified module as the documentation root\n rather than nesting it inside a folder."
|
|
},
|
|
"generate_readme": {
|
|
"name": "generate_readme",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_readme",
|
|
"signature": "<bound method Alias.signature of Alias('generate_readme', 'docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_readme')>",
|
|
"docstring": "Generate a `README.md` file from the root module docstring.\n\nNotes:\n - If `module_is_source` is True, `README.md` is written to the\n project root directory.\n - If False, README generation is currently not implemented.\n\nArgs:\n project (Project):\n Project model containing documentation metadata.\n\n docs_dir (Path):\n Directory containing generated documentation sources.\n\n module_is_source (bool | None):\n Whether the module is treated as the project source root.\n\n readme_dir (Path | None):\n Directory where the generated README.md should be written.\n Defaults to the parent of `docs_dir`."
|
|
}
|
|
}
|
|
},
|
|
"generate_sources": {
|
|
"name": "generate_sources",
|
|
"kind": "function",
|
|
"path": "docforge.cli.mkdocs_utils.generate_sources",
|
|
"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``."
|
|
},
|
|
"build_lib_nav": {
|
|
"name": "build_lib_nav",
|
|
"kind": "function",
|
|
"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_wiki_nav_block": {
|
|
"name": "build_wiki_nav_block",
|
|
"kind": "function",
|
|
"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', 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."
|
|
}
|
|
}
|
|
}
|
|
} |