From c8f32bf4b989d8813346758b06bd8528b9d73257 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 21 Feb 2026 20:34:01 +0530 Subject: [PATCH 1/5] added root index.md --- .run/pytest.run.xml | 31 ----------- docforge/renderers/mkdocs_renderer.py | 77 ++++++++++++++++++++++---- docforge/renderers/mkdocs_renderer.pyi | 6 ++ docs/docforge/cli/index.md | 4 ++ docs/docforge/index.md | 6 ++ docs/docforge/loaders/index.md | 1 + docs/docforge/models/index.md | 3 + docs/docforge/nav/index.md | 3 + docs/docforge/renderers/index.md | 3 + docs/docforge/servers/index.md | 1 + docs/index.md | 5 ++ mkdocs.yml | 4 +- 12 files changed, 98 insertions(+), 46 deletions(-) delete mode 100644 .run/pytest.run.xml create mode 100644 docs/index.md diff --git a/.run/pytest.run.xml b/.run/pytest.run.xml deleted file mode 100644 index b923b9b..0000000 --- a/.run/pytest.run.xml +++ /dev/null @@ -1,31 +0,0 @@ - - - - - \ No newline at end of file diff --git a/docforge/renderers/mkdocs_renderer.py b/docforge/renderers/mkdocs_renderer.py index 8edd3d1..7bb49e6 100644 --- a/docforge/renderers/mkdocs_renderer.py +++ b/docforge/renderers/mkdocs_renderer.py @@ -1,10 +1,15 @@ """ -This module implements the MkDocsRenderer, which generates Markdown source files -compatible with the MkDocs 'material' theme and 'mkdocstrings' extension. +MkDocsRenderer + +Generates Markdown source files compatible with MkDocs Material +and mkdocstrings, ensuring: + +- Root index.md always exists +- Parent package indexes are created automatically +- Child modules are linked in parent index files """ from pathlib import Path - from docforge.models import Project @@ -16,6 +21,9 @@ class MkDocsRenderer: name = "mkdocs" + # ------------------------- + # Public API + # ------------------------- def generate_sources(self, project: Project, out_dir: Path) -> None: """ Produce a set of Markdown files in the output directory based on the @@ -25,6 +33,9 @@ class MkDocsRenderer: project: The project models to render. out_dir: Target directory for documentation files. """ + out_dir.mkdir(parents=True, exist_ok=True) + self._ensure_root_index(project, out_dir) + modules = list(project.get_all_modules()) paths = {m.path for m in modules} @@ -53,26 +64,25 @@ class MkDocsRenderer: parts = module.path.split(".") if module.path in packages: - # package → index.md + # Package → directory/index.md dir_path = out_dir.joinpath(*parts) dir_path.mkdir(parents=True, exist_ok=True) - md_path = dir_path / "index.md" - title = parts[-1].replace("_", " ").title() + link_target = f"{parts[-1]}/" else: - # leaf module → .md + # Leaf module → parent_dir/.md dir_path = out_dir.joinpath(*parts[:-1]) dir_path.mkdir(parents=True, exist_ok=True) - md_path = dir_path / f"{parts[-1]}.md" - title = parts[-1].replace("_", " ").title() + link_target = f"{parts[-1]}.md" + title = parts[-1].replace("_", " ").title() content = self._render_markdown(title, module.path) - if md_path.exists() and md_path.read_text(encoding="utf-8") == content: - return + if not md_path.exists() or md_path.read_text(encoding="utf-8") != content: + md_path.write_text(content, encoding="utf-8") - md_path.write_text(content, encoding="utf-8") + self._ensure_parent_index(parts, out_dir, link_target, title) def _render_markdown(self, title: str, module_path: str) -> str: """ @@ -89,3 +99,46 @@ class MkDocsRenderer: f"# {title}\n\n" f"::: {module_path}\n" ) + + def _ensure_root_index( + self, + project: Project, + out_dir: Path + ) -> None: + root_index = out_dir / "index.md" + + if not root_index.exists(): + root_index.write_text( + f"# {project.name}\n\n" + "## Modules\n\n", + encoding="utf-8", + ) + + def _ensure_parent_index( + self, + parts: list[str], + out_dir: Path, + link_target: str, + title: str, + ) -> None: + if len(parts) == 1: + parent_index = out_dir / "index.md" + link = f"- [{title}]({link_target})\n" + else: + parent_dir = out_dir.joinpath(*parts[:-1]) + parent_dir.mkdir(parents=True, exist_ok=True) + parent_index = parent_dir / "index.md" + + link = f"- [{title}]({link_target})\n" + + if not parent_index.exists(): + parent_title = parts[-2].replace("_", " ").title() + parent_index.write_text( + f"# {parent_title}\n\n", + encoding="utf-8", + ) + + content = parent_index.read_text(encoding="utf-8") + + if link not in content: + parent_index.write_text(content + link, encoding="utf-8") diff --git a/docforge/renderers/mkdocs_renderer.pyi b/docforge/renderers/mkdocs_renderer.pyi index b3f3f7c..3b13d76 100644 --- a/docforge/renderers/mkdocs_renderer.pyi +++ b/docforge/renderers/mkdocs_renderer.pyi @@ -8,10 +8,16 @@ class MkDocsRenderer: name: str def generate_sources(self, project: Project, out_dir: Path) -> None: ... + def _write_module( self, module: Module, packages: Set[str], out_dir: Path, ) -> None: ... + def _render_markdown(self, title: str, module_path: str) -> str: ... + + def _ensure_root_index(self, project, out_dir) -> None: ... + + def _ensure_parent_index(self, parts, out_dir, link_target, title) -> None: ... diff --git a/docs/docforge/cli/index.md b/docs/docforge/cli/index.md index 3b215dd..b5ece30 100644 --- a/docs/docforge/cli/index.md +++ b/docs/docforge/cli/index.md @@ -1,3 +1,7 @@ # Cli ::: docforge.cli +- [Commands](commands.md) +- [Main](main.md) +- [Mcp Utils](mcp_utils.md) +- [Mkdocs Utils](mkdocs_utils.md) diff --git a/docs/docforge/index.md b/docs/docforge/index.md index 86fda32..d6800dc 100644 --- a/docs/docforge/index.md +++ b/docs/docforge/index.md @@ -1,3 +1,9 @@ # Docforge ::: docforge +- [Cli](cli/) +- [Loaders](loaders/) +- [Models](models/) +- [Nav](nav/) +- [Renderers](renderers/) +- [Servers](servers/) diff --git a/docs/docforge/loaders/index.md b/docs/docforge/loaders/index.md index 9dc53f9..2cbb874 100644 --- a/docs/docforge/loaders/index.md +++ b/docs/docforge/loaders/index.md @@ -1,3 +1,4 @@ # Loaders ::: docforge.loaders +- [Griffe Loader](griffe_loader.md) diff --git a/docs/docforge/models/index.md b/docs/docforge/models/index.md index 3d02dbd..f16cc48 100644 --- a/docs/docforge/models/index.md +++ b/docs/docforge/models/index.md @@ -1,3 +1,6 @@ # Models ::: docforge.models +- [Module](module.md) +- [Object](object.md) +- [Project](project.md) diff --git a/docs/docforge/nav/index.md b/docs/docforge/nav/index.md index 95e83b3..b09bf84 100644 --- a/docs/docforge/nav/index.md +++ b/docs/docforge/nav/index.md @@ -1,3 +1,6 @@ # Nav ::: docforge.nav +- [Mkdocs](mkdocs.md) +- [Resolver](resolver.md) +- [Spec](spec.md) diff --git a/docs/docforge/renderers/index.md b/docs/docforge/renderers/index.md index 53fb5a8..28d61c4 100644 --- a/docs/docforge/renderers/index.md +++ b/docs/docforge/renderers/index.md @@ -1,3 +1,6 @@ # Renderers ::: docforge.renderers +- [Base](base.md) +- [Mcp Renderer](mcp_renderer.md) +- [Mkdocs Renderer](mkdocs_renderer.md) diff --git a/docs/docforge/servers/index.md b/docs/docforge/servers/index.md index 6297158..22e4b69 100644 --- a/docs/docforge/servers/index.md +++ b/docs/docforge/servers/index.md @@ -1,3 +1,4 @@ # Servers ::: docforge.servers +- [Mcp Server](mcp_server.md) diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..41e79ac --- /dev/null +++ b/docs/index.md @@ -0,0 +1,5 @@ +# docforge + +## Modules + +- [Docforge](docforge/) diff --git a/mkdocs.yml b/mkdocs.yml index 5b9e7da..72b0e5b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,5 +1,3 @@ -site_name: docforge - theme: name: material palette: @@ -33,7 +31,7 @@ plugins: annotations_path: brief show_root_heading: true group_by_category: true - +site_name: docforge nav: - Home: docforge/index.md - Loaders: -- 2.49.1 From 8829e16af05c1d22b2aa6f22d1ea8fbce46ba83e Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 21 Feb 2026 21:00:14 +0530 Subject: [PATCH 2/5] updated mkdocs configs --- docforge.nav.yml | 40 +++++++++---------- docs/{docforge => }/cli/commands.md | 0 docs/cli/index.md | 3 ++ docs/{docforge => }/cli/main.md | 0 docs/{docforge => }/cli/mcp_utils.md | 0 docs/{docforge => }/cli/mkdocs_utils.md | 0 docs/docforge/cli/index.md | 7 ---- docs/docforge/index.md | 9 ----- docs/docforge/loaders/index.md | 4 -- docs/docforge/models/index.md | 6 --- docs/docforge/nav/index.md | 6 --- docs/docforge/renderers/index.md | 6 --- docs/index.md | 4 +- docs/{docforge => }/loaders/griffe_loader.md | 0 docs/loaders/index.md | 3 ++ docs/models/index.md | 3 ++ docs/{docforge => }/models/module.md | 0 docs/{docforge => }/models/object.md | 0 docs/{docforge => }/models/project.md | 0 docs/nav/index.md | 3 ++ docs/{docforge => }/nav/mkdocs.md | 0 docs/{docforge => }/nav/resolver.md | 0 docs/{docforge => }/nav/spec.md | 0 docs/{docforge => }/renderers/base.md | 0 docs/renderers/index.md | 3 ++ docs/{docforge => }/renderers/mcp_renderer.md | 0 .../renderers/mkdocs_renderer.md | 0 docs/{docforge => }/servers/index.md | 1 - docs/{docforge => }/servers/mcp_server.md | 0 mkdocs.yml | 40 +++++++++---------- 30 files changed, 56 insertions(+), 82 deletions(-) rename docs/{docforge => }/cli/commands.md (100%) create mode 100644 docs/cli/index.md rename docs/{docforge => }/cli/main.md (100%) rename docs/{docforge => }/cli/mcp_utils.md (100%) rename docs/{docforge => }/cli/mkdocs_utils.md (100%) delete mode 100644 docs/docforge/cli/index.md delete mode 100644 docs/docforge/index.md delete mode 100644 docs/docforge/loaders/index.md delete mode 100644 docs/docforge/models/index.md delete mode 100644 docs/docforge/nav/index.md delete mode 100644 docs/docforge/renderers/index.md rename docs/{docforge => }/loaders/griffe_loader.md (100%) create mode 100644 docs/loaders/index.md create mode 100644 docs/models/index.md rename docs/{docforge => }/models/module.md (100%) rename docs/{docforge => }/models/object.md (100%) rename docs/{docforge => }/models/project.md (100%) create mode 100644 docs/nav/index.md rename docs/{docforge => }/nav/mkdocs.md (100%) rename docs/{docforge => }/nav/resolver.md (100%) rename docs/{docforge => }/nav/spec.md (100%) rename docs/{docforge => }/renderers/base.md (100%) create mode 100644 docs/renderers/index.md rename docs/{docforge => }/renderers/mcp_renderer.md (100%) rename docs/{docforge => }/renderers/mkdocs_renderer.md (100%) rename docs/{docforge => }/servers/index.md (51%) rename docs/{docforge => }/servers/mcp_server.md (100%) diff --git a/docforge.nav.yml b/docforge.nav.yml index 9d484b5..c152294 100644 --- a/docforge.nav.yml +++ b/docforge.nav.yml @@ -1,26 +1,26 @@ -home: docforge/index.md +home: index.md groups: Loaders: - - docforge/loaders/index.md - - docforge/loaders/griffe_loader.md + - loaders/index.md + - loaders/griffe_loader.md Models: - - docforge/models/index.md - - docforge/models/module.md - - docforge/models/object.md - - docforge/models/project.md + - models/index.md + - models/module.md + - models/object.md + - models/project.md Navigation: - - docforge/nav/index.md - - docforge/nav/spec.md - - docforge/nav/resolver.md - - docforge/nav/mkdocs.md + - nav/index.md + - nav/spec.md + - nav/resolver.md + - nav/mkdocs.md Renderers: - - docforge/renderers/index.md - - docforge/renderers/base.md - - docforge/renderers/mkdocs_renderer.md - - docforge/renderers/mcp_renderer.md + - renderers/index.md + - renderers/base.md + - renderers/mkdocs_renderer.md + - renderers/mcp_renderer.md CLI: - - docforge/cli/index.md - - docforge/cli/main.md - - docforge/cli/commands.md - - docforge/cli/mcp_utils.md - - docforge/cli/mkdocs_utils.md + - cli/index.md + - cli/main.md + - cli/commands.md + - cli/mcp_utils.md + - cli/mkdocs_utils.md diff --git a/docs/docforge/cli/commands.md b/docs/cli/commands.md similarity index 100% rename from docs/docforge/cli/commands.md rename to docs/cli/commands.md diff --git a/docs/cli/index.md b/docs/cli/index.md new file mode 100644 index 0000000..3b215dd --- /dev/null +++ b/docs/cli/index.md @@ -0,0 +1,3 @@ +# Cli + +::: docforge.cli diff --git a/docs/docforge/cli/main.md b/docs/cli/main.md similarity index 100% rename from docs/docforge/cli/main.md rename to docs/cli/main.md diff --git a/docs/docforge/cli/mcp_utils.md b/docs/cli/mcp_utils.md similarity index 100% rename from docs/docforge/cli/mcp_utils.md rename to docs/cli/mcp_utils.md diff --git a/docs/docforge/cli/mkdocs_utils.md b/docs/cli/mkdocs_utils.md similarity index 100% rename from docs/docforge/cli/mkdocs_utils.md rename to docs/cli/mkdocs_utils.md diff --git a/docs/docforge/cli/index.md b/docs/docforge/cli/index.md deleted file mode 100644 index b5ece30..0000000 --- a/docs/docforge/cli/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Cli - -::: docforge.cli -- [Commands](commands.md) -- [Main](main.md) -- [Mcp Utils](mcp_utils.md) -- [Mkdocs Utils](mkdocs_utils.md) diff --git a/docs/docforge/index.md b/docs/docforge/index.md deleted file mode 100644 index d6800dc..0000000 --- a/docs/docforge/index.md +++ /dev/null @@ -1,9 +0,0 @@ -# Docforge - -::: docforge -- [Cli](cli/) -- [Loaders](loaders/) -- [Models](models/) -- [Nav](nav/) -- [Renderers](renderers/) -- [Servers](servers/) diff --git a/docs/docforge/loaders/index.md b/docs/docforge/loaders/index.md deleted file mode 100644 index 2cbb874..0000000 --- a/docs/docforge/loaders/index.md +++ /dev/null @@ -1,4 +0,0 @@ -# Loaders - -::: docforge.loaders -- [Griffe Loader](griffe_loader.md) diff --git a/docs/docforge/models/index.md b/docs/docforge/models/index.md deleted file mode 100644 index f16cc48..0000000 --- a/docs/docforge/models/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Models - -::: docforge.models -- [Module](module.md) -- [Object](object.md) -- [Project](project.md) diff --git a/docs/docforge/nav/index.md b/docs/docforge/nav/index.md deleted file mode 100644 index b09bf84..0000000 --- a/docs/docforge/nav/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Nav - -::: docforge.nav -- [Mkdocs](mkdocs.md) -- [Resolver](resolver.md) -- [Spec](spec.md) diff --git a/docs/docforge/renderers/index.md b/docs/docforge/renderers/index.md deleted file mode 100644 index 28d61c4..0000000 --- a/docs/docforge/renderers/index.md +++ /dev/null @@ -1,6 +0,0 @@ -# Renderers - -::: docforge.renderers -- [Base](base.md) -- [Mcp Renderer](mcp_renderer.md) -- [Mkdocs Renderer](mkdocs_renderer.md) diff --git a/docs/index.md b/docs/index.md index 41e79ac..96e8919 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,3 @@ # docforge -## Modules - -- [Docforge](docforge/) +::: docforge diff --git a/docs/docforge/loaders/griffe_loader.md b/docs/loaders/griffe_loader.md similarity index 100% rename from docs/docforge/loaders/griffe_loader.md rename to docs/loaders/griffe_loader.md diff --git a/docs/loaders/index.md b/docs/loaders/index.md new file mode 100644 index 0000000..9dc53f9 --- /dev/null +++ b/docs/loaders/index.md @@ -0,0 +1,3 @@ +# Loaders + +::: docforge.loaders diff --git a/docs/models/index.md b/docs/models/index.md new file mode 100644 index 0000000..3d02dbd --- /dev/null +++ b/docs/models/index.md @@ -0,0 +1,3 @@ +# Models + +::: docforge.models diff --git a/docs/docforge/models/module.md b/docs/models/module.md similarity index 100% rename from docs/docforge/models/module.md rename to docs/models/module.md diff --git a/docs/docforge/models/object.md b/docs/models/object.md similarity index 100% rename from docs/docforge/models/object.md rename to docs/models/object.md diff --git a/docs/docforge/models/project.md b/docs/models/project.md similarity index 100% rename from docs/docforge/models/project.md rename to docs/models/project.md diff --git a/docs/nav/index.md b/docs/nav/index.md new file mode 100644 index 0000000..95e83b3 --- /dev/null +++ b/docs/nav/index.md @@ -0,0 +1,3 @@ +# Nav + +::: docforge.nav diff --git a/docs/docforge/nav/mkdocs.md b/docs/nav/mkdocs.md similarity index 100% rename from docs/docforge/nav/mkdocs.md rename to docs/nav/mkdocs.md diff --git a/docs/docforge/nav/resolver.md b/docs/nav/resolver.md similarity index 100% rename from docs/docforge/nav/resolver.md rename to docs/nav/resolver.md diff --git a/docs/docforge/nav/spec.md b/docs/nav/spec.md similarity index 100% rename from docs/docforge/nav/spec.md rename to docs/nav/spec.md diff --git a/docs/docforge/renderers/base.md b/docs/renderers/base.md similarity index 100% rename from docs/docforge/renderers/base.md rename to docs/renderers/base.md diff --git a/docs/renderers/index.md b/docs/renderers/index.md new file mode 100644 index 0000000..53fb5a8 --- /dev/null +++ b/docs/renderers/index.md @@ -0,0 +1,3 @@ +# Renderers + +::: docforge.renderers diff --git a/docs/docforge/renderers/mcp_renderer.md b/docs/renderers/mcp_renderer.md similarity index 100% rename from docs/docforge/renderers/mcp_renderer.md rename to docs/renderers/mcp_renderer.md diff --git a/docs/docforge/renderers/mkdocs_renderer.md b/docs/renderers/mkdocs_renderer.md similarity index 100% rename from docs/docforge/renderers/mkdocs_renderer.md rename to docs/renderers/mkdocs_renderer.md diff --git a/docs/docforge/servers/index.md b/docs/servers/index.md similarity index 51% rename from docs/docforge/servers/index.md rename to docs/servers/index.md index 22e4b69..6297158 100644 --- a/docs/docforge/servers/index.md +++ b/docs/servers/index.md @@ -1,4 +1,3 @@ # Servers ::: docforge.servers -- [Mcp Server](mcp_server.md) diff --git a/docs/docforge/servers/mcp_server.md b/docs/servers/mcp_server.md similarity index 100% rename from docs/docforge/servers/mcp_server.md rename to docs/servers/mcp_server.md diff --git a/mkdocs.yml b/mkdocs.yml index 72b0e5b..fe5897d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -33,28 +33,28 @@ plugins: group_by_category: true site_name: docforge nav: -- Home: docforge/index.md +- Home: index.md - Loaders: - - docforge/loaders/index.md - - docforge/loaders/griffe_loader.md + - loaders/index.md + - loaders/griffe_loader.md - Models: - - docforge/models/index.md - - docforge/models/module.md - - docforge/models/object.md - - docforge/models/project.md + - models/index.md + - models/module.md + - models/object.md + - models/project.md - Navigation: - - docforge/nav/index.md - - docforge/nav/spec.md - - docforge/nav/resolver.md - - docforge/nav/mkdocs.md + - nav/index.md + - nav/spec.md + - nav/resolver.md + - nav/mkdocs.md - Renderers: - - docforge/renderers/index.md - - docforge/renderers/base.md - - docforge/renderers/mkdocs_renderer.md - - docforge/renderers/mcp_renderer.md + - renderers/index.md + - renderers/base.md + - renderers/mkdocs_renderer.md + - renderers/mcp_renderer.md - CLI: - - docforge/cli/index.md - - docforge/cli/main.md - - docforge/cli/commands.md - - docforge/cli/mcp_utils.md - - docforge/cli/mkdocs_utils.md + - cli/index.md + - cli/main.md + - cli/commands.md + - cli/mcp_utils.md + - cli/mkdocs_utils.md -- 2.49.1 From a2ebd7d19bf6d769b8a96da69dfd8552691b5bd3 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 21 Feb 2026 21:03:10 +0530 Subject: [PATCH 3/5] refresh docs and mcp --- mcp_docs/modules/docforge.cli.commands.json | 18 ++-- mcp_docs/modules/docforge.cli.json | 34 +++---- mcp_docs/modules/docforge.cli.mcp_utils.json | 4 +- .../modules/docforge.cli.mkdocs_utils.json | 12 +-- mcp_docs/modules/docforge.json | 95 +++++++++---------- mcp_docs/modules/docforge.renderers.json | 57 +++++------ .../docforge.renderers.mkdocs_renderer.json | 55 +++++------ 7 files changed, 127 insertions(+), 148 deletions(-) diff --git a/mcp_docs/modules/docforge.cli.commands.json b/mcp_docs/modules/docforge.cli.commands.json index 3bf3e1e..1d5d04d 100644 --- a/mcp_docs/modules/docforge.cli.commands.json +++ b/mcp_docs/modules/docforge.cli.commands.json @@ -139,7 +139,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -178,7 +178,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", @@ -319,7 +319,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } }, @@ -334,22 +334,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module: The dotted path of the module to document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n modules: List of module import paths to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." }, "Group": { "name": "Group", diff --git a/mcp_docs/modules/docforge.cli.json b/mcp_docs/modules/docforge.cli.json index 0b3ab64..51c5aad 100644 --- a/mcp_docs/modules/docforge.cli.json +++ b/mcp_docs/modules/docforge.cli.json @@ -169,7 +169,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -208,7 +208,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", @@ -349,7 +349,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } }, @@ -364,22 +364,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module: The dotted path of the module to document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n modules: List of module import paths to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." }, "Group": { "name": "Group", @@ -512,8 +512,8 @@ "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } }, @@ -601,7 +601,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -639,28 +639,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "signature": "", + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", + "signature": "", "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." } } diff --git a/mcp_docs/modules/docforge.cli.mcp_utils.json b/mcp_docs/modules/docforge.cli.mcp_utils.json index 607ec05..92c0682 100644 --- a/mcp_docs/modules/docforge.cli.mcp_utils.json +++ b/mcp_docs/modules/docforge.cli.mcp_utils.json @@ -112,8 +112,8 @@ "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } } diff --git a/mcp_docs/modules/docforge.cli.mkdocs_utils.json b/mcp_docs/modules/docforge.cli.mkdocs_utils.json index ccb2494..92af3a4 100644 --- a/mcp_docs/modules/docforge.cli.mkdocs_utils.json +++ b/mcp_docs/modules/docforge.cli.mkdocs_utils.json @@ -81,7 +81,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -119,28 +119,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "signature": "", + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", + "signature": "", "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." } } diff --git a/mcp_docs/modules/docforge.json b/mcp_docs/modules/docforge.json index 0f2176e..4ed1335 100644 --- a/mcp_docs/modules/docforge.json +++ b/mcp_docs/modules/docforge.json @@ -2,7 +2,7 @@ "module": "docforge", "content": { "path": "docforge", - "docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1. **Build Documentation**:\n Introspect your package and generate documentation in one step:\n ```bash\n # Build MkDocs site\n doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n # Build MCP resources\n doc-forge build --mcp --module my_package\n ```\n\n2. **Define Navigation**:\n Create a `docforge.nav.yml` to organize your documentation:\n ```yaml\n home: my_package/index.md\n groups:\n Core API:\n - my_package/core/*.md\n Utilities:\n - my_package/utils.md\n ```\n\n3. **Preview**:\n ```bash\n # Serve MkDocs site\n doc-forge serve --mkdocs\n\n # Serve MCP documentation\n doc-forge serve --mcp\n ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.", + "docstring": "# doc-forge\n\n`doc-forge` is a renderer-agnostic Python documentation compiler designed for\nspeed, flexibility, and beautiful output. It decouples the introspection of\nyour code from the rendering process, allowing you to generate documentation\nfor various platforms (starting with MkDocs) from a single internal models.\n\n## Core Philosophy\n\n`doc-forge` operates on two fundamental principles:\n\n1. **The Atomic Unit is a Python Import Path**: Documentation is organized around the semantic structure of your code (e.g., `mypackage.utils`), not the filesystem.\n2. **The Documentation Compiler Paradigm**: We separate documentation into three distinct phases:\n - **Front-end (Introspection)**: Static analysis of source code and docstrings.\n - **Middle-end (Semantic Model)**: A renderer-neutral internal representation.\n - **Back-end (Renderers)**: Generation of human-facing (MkDocs) or machine-facing (MCP) outputs.\n\n## Documentation Design\n\n`doc-forge` is an \"AI-Native\" documentation compiler. To get the most out of it, design your docstrings with both humans and LLMs in mind:\n\n### For Humans (Readability & Structure)\n- **`__init__.py` as Landing Pages**: Use the docstring of your package's `__init__.py` as the home page. Include overviews, installation instructions, and high-level examples here.\n- **Single Source of Truth**: Keep all technical details in docstrings. This ensures your MkDocs/Sphinx sites stay in sync with the code.\n- **Semantic Hierarchy**: Use standard Markdown headers to structure complex module documentation.\n\n### For LLMs (AI-Native Knowledge)\n- **Model Context Protocol (MCP)**: `doc-forge` exports your docs as structured JSON. This allows AI agents to \"understand\" your API surface area without layout noise.\n- **Canonical Paths**: Use dotted import paths as primary identifiers. AI tools use these to link code usage to documentation.\n- **Type Annotations**: While not in docstrings, `doc-forge` (via Griffe) extracts signatures. Clean type hints dramatically improve an LLM's ability to generate correct code using your library.\n## Available Commands\n\n- **build**: Build documentation (MkDocs site or MCP resources).\n- **serve**: Serve documentation (MkDocs or MCP).\n- **tree**: Visualize the introspected project structure.\n\n## Installation\n\nInstall using `pip` with the optional `mkdocs` dependencies for a complete setup:\n\n```bash\npip install doc-forge\n```\n\n## Quick Start\n\n1. **Build Documentation**:\n Introspect your package and generate documentation in one step:\n ```bash\n # Build MkDocs site\n doc-forge build --mkdocs --module my_package --site-name \"My Docs\"\n\n # Build MCP resources\n doc-forge build --mcp --module my_package\n ```\n\n2. **Define Navigation**:\n Create a `docforge.nav.yml` to organize your documentation:\n ```yaml\n home: my_package/index.md\n groups:\n Core API:\n - my_package/core/*.md\n Utilities:\n - my_package/utils.md\n ```\n\n3. **Preview**:\n ```bash\n # Serve MkDocs site\n doc-forge serve --mkdocs\n\n # Serve MCP documentation\n doc-forge serve --mcp\n ```\n\n## Project Structure\n\n- `docforge.loaders`: Introspects source code using static analysis (`griffe`).\n- `docforge.models`: The internal representation of your project, modules, and objects.\n- `docforge.renderers`: Converters that turn the models into physical files.\n- `docforge.nav`: Managers for logical-to-physical path mapping and navigation.", "objects": { "GriffeLoader": { "name": "GriffeLoader", @@ -53,7 +53,7 @@ "kind": "function", "path": "docforge.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -275,7 +275,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -314,7 +314,7 @@ "kind": "function", "path": "docforge.cli.commands.mkdocs_utils.generate_sources", "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", @@ -455,7 +455,7 @@ "kind": "function", "path": "docforge.cli.commands.mcp_utils.serve", "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } }, @@ -470,22 +470,22 @@ "name": "build", "kind": "function", "path": "docforge.cli.commands.build", - "signature": "", - "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module: The dotted path of the module to document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." + "signature": "", + "docstring": "Build documentation (MkDocs site or MCP resources).\n\nThis command orchestrates the full build process:\n1. Introspects the code (Griffe)\n2. Renders sources (MkDocs Markdown or MCP JSON)\n3. (MkDocs only) Generates config and runs the final site build.\n\nArgs:\n mcp: Use the MCP documentation builder.\n mkdocs: Use the MkDocs documentation builder.\n module_is_source: Module is the source folder and to be treated as the root folder.\n module: The dotted path of the module to the document.\n project_name: Optional override for the project name.\n site_name: (MkDocs) The site display name. Defaults to module name.\n docs_dir: (MkDocs) Target directory for Markdown sources.\n nav_file: (MkDocs) Path to the docforge.nav.yml specification.\n template: (MkDocs) Optional custom mkdocs.yml template.\n mkdocs_yml: (MkDocs) Target path for the generated mkdocs.yml.\n out_dir: (MCP) Target directory for MCP JSON resources." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.commands.serve", - "signature": "", - "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." + "signature": "", + "docstring": "Serve documentation (MkDocs or MCP).\n\nArgs:\n mcp: Serve MCP resources via an MCP server.\n mkdocs: Serve the MkDocs site using the built-in development server.\n module: The dotted path of the module to serve.\n mkdocs_yml: (MkDocs) Path to the mkdocs.yml configuration.\n out_dir: (MCP) Path to the mcp_docs/ directory." }, "tree": { "name": "tree", "kind": "function", "path": "docforge.cli.commands.tree", - "signature": "", - "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n modules: List of module import paths to recursively introspect.\n project_name: Optional override for the project name shown at the root." + "signature": "", + "docstring": "Visualize the project structure in the terminal.\n\nArgs:\n module: The module import path to recursively introspect.\n project_name: Optional override for the project name shown at the root." }, "Group": { "name": "Group", @@ -618,8 +618,8 @@ "name": "serve", "kind": "function", "path": "docforge.cli.mcp_utils.serve", - "signature": "", - "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." + "signature": "", + "docstring": "Serve MCP documentation from a pre-built bundle.\n\nArgs:\n module: The dotted path of the primary module to serve.\n mcp_root: Path to the directory containing index.json, nav.json, and modules/." } } }, @@ -707,7 +707,7 @@ "kind": "function", "path": "docforge.cli.mkdocs_utils.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -745,28 +745,28 @@ "name": "generate_sources", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_sources", - "signature": "", - "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written." + "signature": "", + "docstring": "Generate Markdown source files for the specified module.\n\nArgs:\n module: The dotted path of the primary module to document.\n project_name: Optional override for the project name.\n docs_dir: Directory where the generated Markdown files will be written.\n module_is_source: Module is the source folder and to be treated as the root folder." }, "generate_config": { "name": "generate_config", "kind": "function", "path": "docforge.cli.mkdocs_utils.generate_config", - "signature": "", + "signature": "", "docstring": "Generate an mkdocs.yml configuration file.\n\nArgs:\n docs_dir: Path to the directory containing documentation Markdown files.\n nav_file: Path to the docforge.nav.yml specification.\n template: Optional path to an mkdocs.yml template (overrides built-in).\n out: Path where the final mkdocs.yml will be written.\n site_name: The display name for the documentation site." }, "build": { "name": "build", "kind": "function", "path": "docforge.cli.mkdocs_utils.build", - "signature": "", + "signature": "", "docstring": "Build the documentation site using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." }, "serve": { "name": "serve", "kind": "function", "path": "docforge.cli.mkdocs_utils.serve", - "signature": "", + "signature": "", "docstring": "Serve the documentation site with live-reload using MkDocs.\n\nArgs:\n mkdocs_yml: Path to the mkdocs.yml configuration file." } } @@ -2079,7 +2079,7 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -2465,7 +2465,7 @@ "kind": "module", "path": "docforge.renderers.mkdocs_renderer", "signature": null, - "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.", + "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", "members": { "Path": { "name": "Path", @@ -2525,36 +2525,6 @@ } } }, - "MkDocsRenderer": { - "name": "MkDocsRenderer", - "kind": "class", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", - "members": { - "name": { - "name": "name", - "kind": "attribute", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", - "signature": null, - "docstring": null - }, - "generate_sources": { - "name": "generate_sources", - "kind": "function", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." - } - } - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Set", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", @@ -2605,6 +2575,29 @@ "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." } } + }, + "MkDocsRenderer": { + "name": "MkDocsRenderer", + "kind": "class", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", + "signature": "", + "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "members": { + "name": { + "name": "name", + "kind": "attribute", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", + "signature": null, + "docstring": null + }, + "generate_sources": { + "name": "generate_sources", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", + "signature": "", + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + } + } } } } diff --git a/mcp_docs/modules/docforge.renderers.json b/mcp_docs/modules/docforge.renderers.json index d46becc..81a0102 100644 --- a/mcp_docs/modules/docforge.renderers.json +++ b/mcp_docs/modules/docforge.renderers.json @@ -23,7 +23,7 @@ "kind": "function", "path": "docforge.renderers.MkDocsRenderer.generate_sources", "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." } } }, @@ -409,7 +409,7 @@ "kind": "module", "path": "docforge.renderers.mkdocs_renderer", "signature": null, - "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.", + "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", "members": { "Path": { "name": "Path", @@ -469,36 +469,6 @@ } } }, - "MkDocsRenderer": { - "name": "MkDocsRenderer", - "kind": "class", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", - "members": { - "name": { - "name": "name", - "kind": "attribute", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", - "signature": null, - "docstring": null - }, - "generate_sources": { - "name": "generate_sources", - "kind": "function", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." - } - } - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Set", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", @@ -549,6 +519,29 @@ "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." } } + }, + "MkDocsRenderer": { + "name": "MkDocsRenderer", + "kind": "class", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", + "signature": "", + "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "members": { + "name": { + "name": "name", + "kind": "attribute", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", + "signature": null, + "docstring": null + }, + "generate_sources": { + "name": "generate_sources", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", + "signature": "", + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + } + } } } } diff --git a/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json b/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json index 83b2930..73ce76c 100644 --- a/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json +++ b/mcp_docs/modules/docforge.renderers.mkdocs_renderer.json @@ -2,7 +2,7 @@ "module": "docforge.renderers.mkdocs_renderer", "content": { "path": "docforge.renderers.mkdocs_renderer", - "docstring": "This module implements the MkDocsRenderer, which generates Markdown source files\ncompatible with the MkDocs 'material' theme and 'mkdocstrings' extension.", + "docstring": "MkDocsRenderer\n\nGenerates Markdown source files compatible with MkDocs Material\nand mkdocstrings, ensuring:\n\n- Root index.md always exists\n- Parent package indexes are created automatically\n- Child modules are linked in parent index files", "objects": { "Path": { "name": "Path", @@ -62,36 +62,6 @@ } } }, - "MkDocsRenderer": { - "name": "MkDocsRenderer", - "kind": "class", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", - "signature": "", - "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", - "members": { - "name": { - "name": "name", - "kind": "attribute", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", - "signature": null, - "docstring": null - }, - "generate_sources": { - "name": "generate_sources", - "kind": "function", - "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", - "signature": "", - "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files." - } - } - }, - "Set": { - "name": "Set", - "kind": "alias", - "path": "docforge.renderers.mkdocs_renderer.Set", - "signature": "", - "docstring": null - }, "Module": { "name": "Module", "kind": "class", @@ -142,6 +112,29 @@ "docstring": "Get all top-level objects in the module.\n\nReturns:\n An iterable of DocObject instances." } } + }, + "MkDocsRenderer": { + "name": "MkDocsRenderer", + "kind": "class", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer", + "signature": "", + "docstring": "Renderer that generates Markdown source files formatted for the MkDocs\n'mkdocstrings' plugin.", + "members": { + "name": { + "name": "name", + "kind": "attribute", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.name", + "signature": null, + "docstring": null + }, + "generate_sources": { + "name": "generate_sources", + "kind": "function", + "path": "docforge.renderers.mkdocs_renderer.MkDocsRenderer.generate_sources", + "signature": "", + "docstring": "Produce a set of Markdown files in the output directory based on the\nprovided Project models.\n\nArgs:\n project: The project models to render.\n out_dir: Target directory for documentation files.\n module_is_source: Module is the source folder and to be treated as the root folder." + } + } } } } -- 2.49.1 From 5149034d192dfdc5009ff867a310eaacdd436ed4 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 21 Feb 2026 21:03:49 +0530 Subject: [PATCH 4/5] module is source flag to ensure for single source modules it's not treated as a module but root --- docforge/cli/commands.py | 12 ++++++-- docforge/cli/commands.pyi | 1 + docforge/cli/mkdocs_utils.py | 14 +++++++-- docforge/cli/mkdocs_utils.pyi | 7 ++++- docforge/renderers/mkdocs_renderer.py | 40 ++++++++++++++++++++------ docforge/renderers/mkdocs_renderer.pyi | 12 +++++--- 6 files changed, 69 insertions(+), 17 deletions(-) diff --git a/docforge/cli/commands.py b/docforge/cli/commands.py index 335f818..12305a4 100644 --- a/docforge/cli/commands.py +++ b/docforge/cli/commands.py @@ -18,6 +18,7 @@ def cli() -> None: @cli.command() @click.option("--mcp", is_flag=True, help="Build MCP resources") @click.option("--mkdocs", is_flag=True, help="Build MkDocs site") +@click.option("--module-is-source", is_flag=True, help="Module is source folder and to be treated as root folder") @click.option("--module", help="Python module to document") @click.option("--project-name", help="Project name override") # MkDocs specific @@ -32,6 +33,7 @@ def cli() -> None: def build( mcp: bool, mkdocs: bool, + module_is_source: bool, module: Optional[str], project_name: Optional[str], site_name: Optional[str], @@ -52,7 +54,8 @@ def build( Args: mcp: Use the MCP documentation builder. mkdocs: Use the MkDocs documentation builder. - module: The dotted path of the module to document. + module_is_source: Module is the source folder and to be treated as the root folder. + module: The dotted path of the module to the document. project_name: Optional override for the project name. site_name: (MkDocs) The site display name. Defaults to module name. docs_dir: (MkDocs) Target directory for Markdown sources. @@ -71,7 +74,12 @@ def build( site_name = module click.echo(f"Generating MkDocs sources in {docs_dir}...") - mkdocs_utils.generate_sources(module, project_name, docs_dir) + mkdocs_utils.generate_sources( + module, + docs_dir, + project_name, + module_is_source, + ) click.echo(f"Generating MkDocs config {mkdocs_yml}...") mkdocs_utils.generate_config(docs_dir, nav_file, template, mkdocs_yml, site_name) diff --git a/docforge/cli/commands.pyi b/docforge/cli/commands.pyi index df4f535..a38d851 100644 --- a/docforge/cli/commands.pyi +++ b/docforge/cli/commands.pyi @@ -7,6 +7,7 @@ cli: Group def build( mcp: bool, mkdocs: bool, + module_is_source: bool, module: Optional[str], project_name: Optional[str], site_name: Optional[str], diff --git a/docforge/cli/mkdocs_utils.py b/docforge/cli/mkdocs_utils.py index 5f9f68e..1c135bd 100644 --- a/docforge/cli/mkdocs_utils.py +++ b/docforge/cli/mkdocs_utils.py @@ -6,7 +6,12 @@ from docforge.loaders import GriffeLoader, discover_module_paths from docforge.renderers import MkDocsRenderer from docforge.nav import load_nav_spec, resolve_nav, MkDocsNavEmitter -def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None: +def generate_sources( + module: str, + docs_dir: Path, + project_name: str | None = None, + module_is_source: bool | None = None, +) -> None: """ Generate Markdown source files for the specified module. @@ -14,13 +19,18 @@ def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> N module: The dotted path of the primary module to document. project_name: Optional override for the project name. docs_dir: Directory where the generated Markdown files will be written. + module_is_source: Module is the source folder and to be treated as the root folder. """ loader = GriffeLoader() discovered_paths = discover_module_paths(module) project = loader.load_project(discovered_paths, project_name) renderer = MkDocsRenderer() - renderer.generate_sources(project, docs_dir) + renderer.generate_sources( + project, + docs_dir, + module_is_source, + ) def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: """ diff --git a/docforge/cli/mkdocs_utils.pyi b/docforge/cli/mkdocs_utils.pyi index fc23e03..052bee9 100644 --- a/docforge/cli/mkdocs_utils.pyi +++ b/docforge/cli/mkdocs_utils.pyi @@ -1,6 +1,11 @@ from pathlib import Path -def generate_sources(module: str, project_name: str | None, docs_dir: Path) -> None: ... +def generate_sources( + module: str, + docs_dir: Path, + project_name: str | None = None, + module_is_source: bool | None = None, +) -> None: ... def generate_config(docs_dir: Path, nav_file: Path, template: Path | None, out: Path, site_name: str) -> None: ... def build(mkdocs_yml: Path) -> None: ... def serve(mkdocs_yml: Path) -> None: ... diff --git a/docforge/renderers/mkdocs_renderer.py b/docforge/renderers/mkdocs_renderer.py index 7bb49e6..b851812 100644 --- a/docforge/renderers/mkdocs_renderer.py +++ b/docforge/renderers/mkdocs_renderer.py @@ -10,7 +10,7 @@ and mkdocstrings, ensuring: """ from pathlib import Path -from docforge.models import Project +from docforge.models import Project, Module class MkDocsRenderer: @@ -24,7 +24,12 @@ class MkDocsRenderer: # ------------------------- # Public API # ------------------------- - def generate_sources(self, project: Project, out_dir: Path) -> None: + def generate_sources( + self, + project: Project, + out_dir: Path, + module_is_source: bool | None = None, + ) -> None: """ Produce a set of Markdown files in the output directory based on the provided Project models. @@ -32,6 +37,7 @@ class MkDocsRenderer: Args: project: The project models to render. out_dir: Target directory for documentation files. + module_is_source: Module is the source folder and to be treated as the root folder. """ out_dir.mkdir(parents=True, exist_ok=True) self._ensure_root_index(project, out_dir) @@ -46,12 +52,23 @@ class MkDocsRenderer: } for module in modules: - self._write_module(module, packages, out_dir) + self._write_module( + module, + packages, + out_dir, + module_is_source, + ) # ------------------------- # Internal helpers # ------------------------- - def _write_module(self, module, packages: set[str], out_dir: Path) -> None: + def _write_module( + self, + module: Module, + packages: set[str], + out_dir: Path, + module_is_source: bool | None = None, + ) -> None: """ Write a single module's documentation file. Packages are written as 'index.md' inside their respective directories. @@ -60,29 +77,36 @@ class MkDocsRenderer: module: The module to write. packages: A set of module paths that are identified as packages. out_dir: The base output directory. + module_is_source: Module is the source folder and to be treated as the root folder. """ parts = module.path.split(".") + if module_is_source: + module_name, parts = parts[0], parts[1:] + else: + module_name, parts = parts[0], parts + if module.path in packages: # Package → directory/index.md dir_path = out_dir.joinpath(*parts) dir_path.mkdir(parents=True, exist_ok=True) md_path = dir_path / "index.md" - link_target = f"{parts[-1]}/" + link_target = f"{parts[-1]}/" if parts else None else: # Leaf module → parent_dir/.md dir_path = out_dir.joinpath(*parts[:-1]) dir_path.mkdir(parents=True, exist_ok=True) md_path = dir_path / f"{parts[-1]}.md" - link_target = f"{parts[-1]}.md" + link_target = f"{parts[-1]}.md" if parts else None - title = parts[-1].replace("_", " ").title() + title = parts[-1].replace("_", " ").title() if parts else module_name content = self._render_markdown(title, module.path) if not md_path.exists() or md_path.read_text(encoding="utf-8") != content: md_path.write_text(content, encoding="utf-8") - self._ensure_parent_index(parts, out_dir, link_target, title) + if not module_is_source: + self._ensure_parent_index(parts, out_dir, link_target, title) def _render_markdown(self, title: str, module_path: str) -> str: """ diff --git a/docforge/renderers/mkdocs_renderer.pyi b/docforge/renderers/mkdocs_renderer.pyi index 3b13d76..130e4dc 100644 --- a/docforge/renderers/mkdocs_renderer.pyi +++ b/docforge/renderers/mkdocs_renderer.pyi @@ -1,19 +1,23 @@ from pathlib import Path -from typing import Set - from docforge.models import Project, Module class MkDocsRenderer: name: str - def generate_sources(self, project: Project, out_dir: Path) -> None: ... + def generate_sources( + self, + project: Project, + out_dir: Path, + module_is_source: bool | None = None, + ) -> None: ... def _write_module( self, module: Module, - packages: Set[str], + packages: set[str], out_dir: Path, + module_is_source: bool | None = None, ) -> None: ... def _render_markdown(self, title: str, module_path: str) -> str: ... -- 2.49.1 From ae3b389a3b94b7d741a5323cef9a1f7dac6871d7 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Sat, 21 Feb 2026 21:04:31 +0530 Subject: [PATCH 5/5] renamed pytest to pytests --- .run/pytests.run.xml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .run/pytests.run.xml diff --git a/.run/pytests.run.xml b/.run/pytests.run.xml new file mode 100644 index 0000000..07542e6 --- /dev/null +++ b/.run/pytests.run.xml @@ -0,0 +1,31 @@ + + + + + \ No newline at end of file -- 2.49.1