{ "module": "docforge.cli.mkdocs_utils", "content": { "path": "docforge.cli.mkdocs_utils", "docstring": "# Summary\n\nUtilities for working with MkDocs in the doc-forge CLI.", "objects": { "Path": { "name": "Path", "kind": "alias", "path": "docforge.cli.mkdocs_utils.Path", "signature": "", "docstring": null }, "resources": { "name": "resources", "kind": "alias", "path": "docforge.cli.mkdocs_utils.resources", "signature": "", "docstring": null }, "click": { "name": "click", "kind": "alias", "path": "docforge.cli.mkdocs_utils.click", "signature": "", "docstring": null }, "yaml": { "name": "yaml", "kind": "alias", "path": "docforge.cli.mkdocs_utils.yaml", "signature": "", "docstring": null }, "GriffeLoader": { "name": "GriffeLoader", "kind": "class", "path": "docforge.cli.mkdocs_utils.GriffeLoader", "signature": "", "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.", "members": { "load_project": { "name": "load_project", "kind": "function", "path": "docforge.cli.mkdocs_utils.GriffeLoader.load_project", "signature": "", "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, optional):\n Optional override for the project name. Defaults to the top-level\n name of the first module.\n\n skip_import_errors (bool, optional):\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": "", "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." } } }, "discover_module_paths": { "name": "discover_module_paths", "kind": "function", "path": "docforge.cli.mkdocs_utils.discover_module_paths", "signature": "", "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, optional):\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." }, "MkDocsRenderer": { "name": "MkDocsRenderer", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer", "signature": "", "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": "", "docstring": null }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", "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, optional):\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": "", "docstring": "Generate a `README.md` file from the root module docstring.\n\nBehavior:\n\n- If `module_is_source` is True, `README.md` is written to the project\n 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, optional):\n Whether the module is treated as the project source root." } } }, "load_nav_spec": { "name": "load_nav_spec", "kind": "function", "path": "docforge.cli.mkdocs_utils.load_nav_spec", "signature": "", "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 to the navigation specification file.\n\nReturns:\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": "", "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: Navigation specification describing documentation layout.\n docs_root: Root directory containing documentation Markdown files.\n\nReturns:\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." }, "MkDocsNavEmitter": { "name": "MkDocsNavEmitter", "kind": "class", "path": "docforge.cli.mkdocs_utils.MkDocsNavEmitter", "signature": "", "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": "", "docstring": "Generate a navigation structure for ``mkdocs.yml``.\n\nArgs:\n nav: Resolved navigation data describing documentation groups\n and their associated Markdown files.\n\nReturns:\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." } } }, "generate_sources": { "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", "signature": "", "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 (Optional[str]):\n Optional override for the project name used in documentation metadata.\n\n module_is_source (Optional[bool]):\n If True, treat the specified module directory as the project root\n rather than a nested module." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", "signature": "", "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.\n\nArgs:\n docs_dir (Path):\n Directory containing generated documentation Markdown files.\n\n nav_file (Path):\n Path to the `docforge.nav.yml` navigation specification.\n\n template (Optional[Path]):\n Optional path to a custom MkDocs configuration template. If not\n provided, a built-in template will be used.\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\nRaises:\n click.FileError:\n If the navigation specification or template file cannot be found." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", "signature": "", "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." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", "signature": "", "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." } } } }