doc-forge/mcp_docs/modules/docforge.cli.mkdocs_utils.json

{
  "module": "docforge.cli.mkdocs_utils",
  "content": {
    "path": "docforge.cli.mkdocs_utils",
    "docstring": null,
    "objects": {
      "Path": {
        "name": "Path",
        "kind": "alias",
        "path": "docforge.cli.mkdocs_utils.Path",
        "signature": "<bound method Alias.signature of Alias('Path', 'pathlib.Path')>",
        "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
      },
      "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.",
        "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 of dotted module import paths to load.\n    project_name: Optional override for the project name. Defaults\n        to the top-level name of the first module.\n    skip_import_errors: If True, modules that fail to load will be\n        skipped instead of raising an error.\n\nReturns:\n    A populated ``Project`` instance containing the loaded modules.\n\nRaises:\n    ValueError: If no module paths are provided.\n    ImportError: If a module fails to load and\n        ``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: Dotted import path of the module.\n\nReturns:\n    A populated ``Module`` instance."
          }
        }
      },
      "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: Top-level package name to discover modules from.\n    project_root: Root directory used to resolve module paths. If not\n        provided, the current working directory is used.\n\nReturns:\n    A sorted list of unique dotted module import paths.\n\nRaises:\n    FileNotFoundError: If the specified package directory does not exist."
      },
      "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 model containing modules to document.\n    out_dir: Directory where generated Markdown files will be written.\n    module_is_source: If True, treat the specified module as the\n        documentation root 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\nBehavior:\n\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 model containing documentation metadata.\n    docs_dir: Directory containing generated documentation sources.\n    module_is_source: Whether the module is treated as the project\n        source root."
          }
        }
      },
      "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 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": "<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: 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": "<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: 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": "<bound method Function.signature of Function('generate_sources', 10, 47)>",
        "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: Python module import path used as the entry point for\n        documentation generation.\n    docs_dir: Directory where the generated Markdown files will be written.\n    project_name: Optional override for the project name used in\n        documentation metadata.\n    module_is_source: If True, treat the specified module directory as\n        the project root rather than a nested module."
      },
      "generate_config": {
        "name": "generate_config",
        "kind": "function",
        "path": "docforge.cli.mkdocs_utils.generate_config",
        "signature": "<bound method Function.signature of Function('generate_config', 50, 100)>",
        "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: Directory containing generated documentation Markdown files.\n    nav_file: Path to the ``docforge.nav.yml`` navigation specification.\n    template: Optional path to a custom MkDocs configuration template.\n        If not provided, a built-in template will be used.\n    out: Destination path where the generated ``mkdocs.yml`` file\n        will be written.\n    site_name: Display name for the generated documentation site.\n\nRaises:\n    click.FileError: If the navigation specification or template\n        file cannot be found."
      },
      "build": {
        "name": "build",
        "kind": "function",
        "path": "docforge.cli.mkdocs_utils.build",
        "signature": "<bound method Function.signature of Function('build', 103, 122)>",
        "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: 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', 125, 142)>",
        "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 to the ``mkdocs.yml`` configuration file.\n\nRaises:\n    click.ClickException: If the configuration file does not exist."
      }
    }
  }
}