diff --git a/README.md b/README.md index 145070d..8d437bc 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ doc-forge server mypackage ### Python API ```python -from docforge.loader import GriffeLoader +from docforge.loaders import GriffeLoader from docforge.renderers import MkDocsRenderer from pathlib import Path @@ -70,6 +70,7 @@ renderer.generate_sources(project, Path("docs")) # Build final documentation from docforge.renderers.base import RendererConfig + config = RendererConfig(Path("docs"), project) renderer.build(config) ``` diff --git a/docforge.nav.yml b/docforge.nav.yml index 6c2dc22..1fd3d8a 100644 --- a/docforge.nav.yml +++ b/docforge.nav.yml @@ -1,13 +1,13 @@ home: docforge/index.md groups: - Loader: - - docforge/loader/index.md - - docforge/loader/griffe_loader.md - Model: - - docforge/model/index.md - - docforge/model/module.md - - docforge/model/object.md - - docforge/model/project.md + Loaders: + - docforge/loaders/index.md + - docforge/loaders/griffe_loader.md + Models: + - docforge/models/index.md + - docforge/models/module.md + - docforge/models/object.md + - docforge/models/project.md Navigation: - docforge/nav/index.md - docforge/nav/spec.md diff --git a/docforge/__init__.py b/docforge/__init__.py index c99bf33..d30c6ca 100644 --- a/docforge/__init__.py +++ b/docforge/__init__.py @@ -4,7 +4,7 @@ `doc-forge` is a renderer-agnostic Python documentation compiler designed for speed, flexibility, and beautiful output. It decouples the introspection of your code from the rendering process, allowing you to generate documentation -for various platforms (starting with MkDocs) from a single internal model. +for various platforms (starting with MkDocs) from a single internal models. ## Installation @@ -45,16 +45,16 @@ pip install doc-forge ## Project Structure -- `docforge.loader`: Introspects source code using static analysis (`griffe`). -- `docforge.model`: The internal representation of your project, modules, and objects. -- `docforge.renderers`: Converters that turn the model into physical files. +- `docforge.loaders`: Introspects source code using static analysis (`griffe`). +- `docforge.models`: The internal representation of your project, modules, and objects. +- `docforge.renderers`: Converters that turn the models into physical files. - `docforge.nav`: Managers for logical-to-physical path mapping and navigation. """ -from .loader import GriffeLoader, discover_module_paths +from .loaders import GriffeLoader, discover_module_paths from .renderers import MkDocsRenderer from .cli import main -from . import model +from . import models __all__ = [ "GriffeLoader", diff --git a/docforge/__init__.pyi b/docforge/__init__.pyi index b5504c2..b3c7ed0 100644 --- a/docforge/__init__.pyi +++ b/docforge/__init__.pyi @@ -1,7 +1,7 @@ -from .loader import GriffeLoader, discover_module_paths +from .loaders import GriffeLoader, discover_module_paths from .renderers import MkDocsRenderer from .cli import main -from . import model +from . import models __all__ = [ "GriffeLoader", diff --git a/docforge/cli/main.py b/docforge/cli/main.py index b20b6c6..ce94dea 100644 --- a/docforge/cli/main.py +++ b/docforge/cli/main.py @@ -8,7 +8,7 @@ from typing import Sequence, Optional import click -from docforge.loader import GriffeLoader, discover_module_paths +from docforge.loaders import GriffeLoader, discover_module_paths from docforge.renderers.mkdocs import MkDocsRenderer from docforge.cli.mkdocs import mkdocs_cmd diff --git a/docforge/loader/__init__.py b/docforge/loaders/__init__.py similarity index 87% rename from docforge/loader/__init__.py rename to docforge/loaders/__init__.py index 6512b4f..2845f8c 100644 --- a/docforge/loader/__init__.py +++ b/docforge/loaders/__init__.py @@ -1,7 +1,7 @@ """ # Loader Layer -The `docforge.loader` package is responsible for discovering Python source files +The `docforge.loaders` package is responsible for discovering Python source files and extracting their documentation using static analysis. ## Core Features diff --git a/docforge/loader/__init__.pyi b/docforge/loaders/__init__.pyi similarity index 100% rename from docforge/loader/__init__.pyi rename to docforge/loaders/__init__.pyi diff --git a/docforge/loader/griffe_loader.py b/docforge/loaders/griffe_loader.py similarity index 98% rename from docforge/loader/griffe_loader.py rename to docforge/loaders/griffe_loader.py index bbf2b18..d08b8b2 100644 --- a/docforge/loader/griffe_loader.py +++ b/docforge/loaders/griffe_loader.py @@ -1,6 +1,6 @@ """ This module provides the GriffeLoader, which uses the 'griffe' library to -introspect Python source code and populate the doc-forge Project model. +introspect Python source code and populate the doc-forge Project models. """ import logging @@ -15,7 +15,7 @@ from griffe import ( AliasResolutionError, ) -from docforge.model import Module, Project, DocObject +from docforge.models import Module, Project, DocObject logger = logging.getLogger(__name__) @@ -83,7 +83,7 @@ class GriffeLoader: skip_import_errors: bool = None, ) -> Project: """ - Load multiple modules and combine them into a single Project model. + Load multiple modules and combine them into a single Project models. Args: module_paths: A list of dotted paths to the modules to load. @@ -116,7 +116,7 @@ class GriffeLoader: def load_module(self, path: str) -> Module: """ - Load a single module and convert its introspection data into the docforge model. + Load a single module and convert its introspection data into the docforge models. Args: path: The dotted path of the module to load. diff --git a/docforge/loader/griffe_loader.pyi b/docforge/loaders/griffe_loader.pyi similarity index 88% rename from docforge/loader/griffe_loader.pyi rename to docforge/loaders/griffe_loader.pyi index 32229cf..037f147 100644 --- a/docforge/loader/griffe_loader.pyi +++ b/docforge/loaders/griffe_loader.pyi @@ -1,7 +1,7 @@ from typing import List, Optional from pathlib import Path -from docforge.model import Module, Project +from docforge.models import Module, Project def discover_module_paths( @@ -12,7 +12,7 @@ def discover_module_paths( class GriffeLoader: - """Griffe-based introspection loader. + """Griffe-based introspection loaders. This is the only supported introspection backend in doc-forge. """ diff --git a/docforge/model/__init__.py b/docforge/models/__init__.py similarity index 88% rename from docforge/model/__init__.py rename to docforge/models/__init__.py index 19b9ee8..58e0d58 100644 --- a/docforge/model/__init__.py +++ b/docforge/models/__init__.py @@ -1,7 +1,7 @@ """ # Model Layer -The `docforge.model` package provides the core data structures used to represent +The `docforge.models` package provides the core data structures used to represent Python source code in a documentation-focused hierarchy. ## Key Components diff --git a/docforge/model/__init__.pyi b/docforge/models/__init__.pyi similarity index 100% rename from docforge/model/__init__.pyi rename to docforge/models/__init__.pyi diff --git a/docforge/model/module.py b/docforge/models/module.py similarity index 92% rename from docforge/model/module.py rename to docforge/models/module.py index e741a55..498bfc9 100644 --- a/docforge/model/module.py +++ b/docforge/models/module.py @@ -1,12 +1,12 @@ """ This module defines the Module class, which represents a Python module or package -in the doc-forge documentation model. It acts as a container for top-level +in the doc-forge documentation models. It acts as a container for top-level documented objects. """ from typing import Dict, Iterable, Optional -from docforge.model.object import DocObject +from docforge.models.object import DocObject class Module: diff --git a/docforge/model/module.pyi b/docforge/models/module.pyi similarity index 91% rename from docforge/model/module.pyi rename to docforge/models/module.pyi index 580796c..e5145be 100644 --- a/docforge/model/module.pyi +++ b/docforge/models/module.pyi @@ -1,6 +1,6 @@ from typing import Dict, Iterable, Optional -from docforge.model.object import DocObject +from docforge.models.object import DocObject class Module: diff --git a/docforge/model/object.py b/docforge/models/object.py similarity index 96% rename from docforge/model/object.py rename to docforge/models/object.py index e1b625d..666ca2b 100644 --- a/docforge/model/object.py +++ b/docforge/models/object.py @@ -1,6 +1,6 @@ """ This module defines the DocObject class, the fundamental recursive unit of the -doc-forge documentation model. A DocObject represents a single Python entity +doc-forge documentation models. A DocObject represents a single Python entity (class, function, method, or attribute) and its nested members. """ diff --git a/docforge/model/object.pyi b/docforge/models/object.pyi similarity index 100% rename from docforge/model/object.pyi rename to docforge/models/object.pyi diff --git a/docforge/model/project.py b/docforge/models/project.py similarity index 97% rename from docforge/model/project.py rename to docforge/models/project.py index c444958..81c036f 100644 --- a/docforge/model/project.py +++ b/docforge/models/project.py @@ -5,7 +5,7 @@ project. It aggregates multiple Module instances into a single named entity. from typing import Dict, Iterable -from docforge.model.module import Module +from docforge.models.module import Module class Project: diff --git a/docforge/model/project.pyi b/docforge/models/project.pyi similarity index 90% rename from docforge/model/project.pyi rename to docforge/models/project.pyi index f7d1062..95f7844 100644 --- a/docforge/model/project.pyi +++ b/docforge/models/project.pyi @@ -1,6 +1,6 @@ from typing import Dict, Iterable -from docforge.model.module import Module +from docforge.models.module import Module class Project: diff --git a/docforge/renderers/__init__.py b/docforge/renderers/__init__.py index fb9792a..26de409 100644 --- a/docforge/renderers/__init__.py +++ b/docforge/renderers/__init__.py @@ -2,7 +2,7 @@ # Renderers Layer The `docforge.renderers` package handles the transformation of the internal -documentation model into physical files formatted for specific documentation +documentation models into physical files formatted for specific documentation engines. ## Current Implementations diff --git a/docforge/renderers/base.py b/docforge/renderers/base.py index b630a0c..e688803 100644 --- a/docforge/renderers/base.py +++ b/docforge/renderers/base.py @@ -7,7 +7,7 @@ DocRenderer protocol. from pathlib import Path from typing import Protocol -from docforge.model import Project +from docforge.models import Project class RendererConfig: @@ -16,7 +16,7 @@ class RendererConfig: Args: out_dir: The directory where documentation files should be written. - project: The introspected project model to be rendered. + project: The introspected project models to be rendered. """ def __init__(self, out_dir: Path, project: Project) -> None: @@ -40,7 +40,7 @@ class DocRenderer(Protocol): Generate renderer-specific source files for the given project. Args: - project: The project model containing modules and objects. + project: The project models containing modules and objects. out_dir: Target directory for the generated files. """ ... diff --git a/docforge/renderers/base.pyi b/docforge/renderers/base.pyi index 4b2d1e6..5800b4f 100644 --- a/docforge/renderers/base.pyi +++ b/docforge/renderers/base.pyi @@ -1,7 +1,7 @@ from pathlib import Path from typing import Protocol -from docforge.model import Project +from docforge.models import Project class RendererConfig: diff --git a/docforge/renderers/mkdocs.py b/docforge/renderers/mkdocs.py index 9d9f5e3..8edd3d1 100644 --- a/docforge/renderers/mkdocs.py +++ b/docforge/renderers/mkdocs.py @@ -5,7 +5,7 @@ compatible with the MkDocs 'material' theme and 'mkdocstrings' extension. from pathlib import Path -from docforge.model import Project +from docforge.models import Project class MkDocsRenderer: @@ -19,10 +19,10 @@ class MkDocsRenderer: def generate_sources(self, project: Project, out_dir: Path) -> None: """ Produce a set of Markdown files in the output directory based on the - provided Project model. + provided Project models. Args: - project: The project model to render. + project: The project models to render. out_dir: Target directory for documentation files. """ modules = list(project.get_all_modules()) diff --git a/docforge/renderers/mkdocs.pyi b/docforge/renderers/mkdocs.pyi index 8286938..b3f3f7c 100644 --- a/docforge/renderers/mkdocs.pyi +++ b/docforge/renderers/mkdocs.pyi @@ -1,7 +1,7 @@ from pathlib import Path from typing import Set -from docforge.model import Project, Module +from docforge.models import Project, Module class MkDocsRenderer: diff --git a/docs/docforge/loader/griffe_loader.md b/docs/docforge/loader/griffe_loader.md deleted file mode 100644 index dd9eb0f..0000000 --- a/docs/docforge/loader/griffe_loader.md +++ /dev/null @@ -1,3 +0,0 @@ -# Griffe Loader - -::: docforge.loader.griffe_loader diff --git a/docs/docforge/loader/index.md b/docs/docforge/loader/index.md deleted file mode 100644 index 76a96a9..0000000 --- a/docs/docforge/loader/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Loader - -::: docforge.loader diff --git a/docs/docforge/loaders/griffe_loader.md b/docs/docforge/loaders/griffe_loader.md new file mode 100644 index 0000000..21d8766 --- /dev/null +++ b/docs/docforge/loaders/griffe_loader.md @@ -0,0 +1,3 @@ +# Griffe Loader + +::: docforge.loaders.griffe_loader diff --git a/docs/docforge/loaders/index.md b/docs/docforge/loaders/index.md new file mode 100644 index 0000000..9dc53f9 --- /dev/null +++ b/docs/docforge/loaders/index.md @@ -0,0 +1,3 @@ +# Loaders + +::: docforge.loaders diff --git a/docs/docforge/model/index.md b/docs/docforge/model/index.md deleted file mode 100644 index f139349..0000000 --- a/docs/docforge/model/index.md +++ /dev/null @@ -1,3 +0,0 @@ -# Model - -::: docforge.model diff --git a/docs/docforge/model/module.md b/docs/docforge/model/module.md deleted file mode 100644 index ab8c0f5..0000000 --- a/docs/docforge/model/module.md +++ /dev/null @@ -1,3 +0,0 @@ -# Module - -::: docforge.model.module diff --git a/docs/docforge/model/object.md b/docs/docforge/model/object.md deleted file mode 100644 index aaee0e3..0000000 --- a/docs/docforge/model/object.md +++ /dev/null @@ -1,3 +0,0 @@ -# Object - -::: docforge.model.object diff --git a/docs/docforge/model/project.md b/docs/docforge/model/project.md deleted file mode 100644 index 3b6682f..0000000 --- a/docs/docforge/model/project.md +++ /dev/null @@ -1,3 +0,0 @@ -# Project - -::: docforge.model.project diff --git a/docs/docforge/models/index.md b/docs/docforge/models/index.md new file mode 100644 index 0000000..3d02dbd --- /dev/null +++ b/docs/docforge/models/index.md @@ -0,0 +1,3 @@ +# Models + +::: docforge.models diff --git a/docs/docforge/models/module.md b/docs/docforge/models/module.md new file mode 100644 index 0000000..945994c --- /dev/null +++ b/docs/docforge/models/module.md @@ -0,0 +1,3 @@ +# Module + +::: docforge.models.module diff --git a/docs/docforge/models/object.md b/docs/docforge/models/object.md new file mode 100644 index 0000000..8e9a603 --- /dev/null +++ b/docs/docforge/models/object.md @@ -0,0 +1,3 @@ +# Object + +::: docforge.models.object diff --git a/docs/docforge/models/project.md b/docs/docforge/models/project.md new file mode 100644 index 0000000..64db98e --- /dev/null +++ b/docs/docforge/models/project.md @@ -0,0 +1,3 @@ +# Project + +::: docforge.models.project diff --git a/mkdocs.yml b/mkdocs.yml index 0941ebd..2a65949 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,14 +36,14 @@ plugins: nav: - Home: docforge/index.md -- Loader: - - docforge/loader/index.md - - docforge/loader/griffe_loader.md -- Model: - - docforge/model/index.md - - docforge/model/module.md - - docforge/model/object.md - - docforge/model/project.md +- Loaders: + - docforge/loaders/index.md + - docforge/loaders/griffe_loader.md +- Models: + - docforge/models/index.md + - docforge/models/module.md + - docforge/models/object.md + - docforge/models/project.md - Navigation: - docforge/nav/index.md - docforge/nav/spec.md diff --git a/tests/renderers/test_mkdocs_content.py b/tests/renderers/test_mkdocs_content.py index 1669cd4..afc3f47 100644 --- a/tests/renderers/test_mkdocs_content.py +++ b/tests/renderers/test_mkdocs_content.py @@ -1,7 +1,7 @@ from pathlib import Path from docforge import MkDocsRenderer -from docforge.model import Project, Module +from docforge.models import Project, Module def test_mkdocs_file_content(tmp_path: Path): diff --git a/tests/renderers/test_mkdocs_idempotency.py b/tests/renderers/test_mkdocs_idempotency.py index 755da68..0cdfdb2 100644 --- a/tests/renderers/test_mkdocs_idempotency.py +++ b/tests/renderers/test_mkdocs_idempotency.py @@ -1,7 +1,7 @@ from pathlib import Path from docforge import MkDocsRenderer -from docforge.model import Project, Module +from docforge.models import Project, Module def test_mkdocs_idempotent(tmp_path: Path): diff --git a/tests/renderers/test_mkdocs_module_coverage.py b/tests/renderers/test_mkdocs_module_coverage.py index 89e5dec..58c750c 100644 --- a/tests/renderers/test_mkdocs_module_coverage.py +++ b/tests/renderers/test_mkdocs_module_coverage.py @@ -1,6 +1,6 @@ from pathlib import Path -from docforge.loader import GriffeLoader, discover_module_paths +from docforge.loaders import GriffeLoader, discover_module_paths from docforge.renderers.mkdocs import MkDocsRenderer @@ -41,21 +41,21 @@ def test_mkdocs_emits_all_modules(tmp_path: Path) -> None: # expected = { # 'docforge/cli/main.md', # 'docforge/renderers/index.md', - # 'docforge/loader/index.md', - # 'docforge/model/index.md', + # 'docforge/loaders/index.md', + # 'docforge/models/index.md', # 'docforge/nav/index.md', # 'docforge/renderers/mkdocs.md', # 'docforge/index.md', - # 'docforge/loader/griffe_loader.md', - # 'docforge/model/object.md', + # 'docforge/loaders/griffe_loader.md', + # 'docforge/models/object.md', # 'docforge/cli/index.md', # 'docforge/nav/resolver.md', # 'docforge/renderers/base.md', # 'docforge/nav/mkdocs.md', # 'docforge/nav/spec.md', - # 'docforge/model/module.md', + # 'docforge/models/module.md', # 'docforge/cli/mkdocs.md', - # 'docforge/model/project.md' + # 'docforge/models/project.md' # } missing = expected - emitted assert not missing, f"Missing markdown files for modules: {missing}" diff --git a/tests/renderers/test_mkdocs_structure.py b/tests/renderers/test_mkdocs_structure.py index d177b1f..1fd6170 100644 --- a/tests/renderers/test_mkdocs_structure.py +++ b/tests/renderers/test_mkdocs_structure.py @@ -1,7 +1,7 @@ from pathlib import Path from docforge import MkDocsRenderer -from docforge.model import Project, Module +from docforge.models import Project, Module def test_mkdocs_directory_structure(tmp_path: Path):