docs/mcp/doc-forge/modules/docforge.cli.mkdocs_utils.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 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---",
    "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",
        "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
      },
      "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', 34, 83)>",
        "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",
        "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."
      },
      "build": {
        "name": "build",
        "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."
      },
      "serve": {
        "name": "serve",
        "kind": "function",
        "path": "docforge.cli.mkdocs_utils.serve",
        "signature": "<bound method Function.signature of Function('serve', 337, 357)>",
        "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."
      }
    }
  }
}