#13 Added Config object for maturity model parser and many small impr…

…ovements to that parser

ekglib/maturity_model_parser/File.py

@@ -1,10 +1,10 @@
 import os
 from pathlib import Path
 
-import mkdocs_gen_files
-
 from ekglib import log_item
 from ekglib.log.various import value_error
+from ekglib.maturity_model_parser.config import Config
+from ekglib.maturity_model_parser.markdown_document import MarkdownDocument
 
 
 class File(object):
@@ -60,10 +60,11 @@ def append_after_second_line(self, data):
             self.file.write('\n' + file_data[len(first_line + second_line):])
 
     @classmethod
-    def copy(cls, mkdocs: bool, from_path: Path, to_path: Path):
-        log_item("Copying", f"{from_path} -> {to_path}")
-        old_file = File.existing_file(mkdocs=mkdocs, path=from_path)
-        new_file = File(mkdocs=mkdocs, path=to_path)
+    def copy(cls, config: Config, from_path: Path, to_path: Path):
+        if config.verbose:
+            log_item("Copying", f"{from_path} -> {to_path}")
+        old_file = File.existing_file(mkdocs=config.mkdocs, path=from_path)
+        new_file = File(mkdocs=config.mkdocs, path=to_path)
         new_file.rewrite_all_file(old_file.read_all_content())
 
 
@@ -73,3 +74,30 @@ def makedirs(path: Path, hint: str):
         os.makedirs(path)
     except FileExistsError:
         return
+
+
+def copy_template_fragment(from_path: Path, config: Config):
+    log_item("Fragment not found", from_path)
+    fragment_base = from_path.name
+    template_path = config.fragments_root / 'template' / fragment_base
+    if not template_path.exists():
+        raise value_error(f"Template not found: {template_path}")
+    makedirs(from_path.parent, "Fragments")
+    File.copy(config=config, from_path=template_path, to_path=from_path)
+
+
+def copy_fragment(md_file: MarkdownDocument, from_path: Path, config: Config):
+    if not from_path.exists():
+        copy_template_fragment(from_path=from_path, config=config)
+    fragment_base = from_path.name
+    log_item("Copying fragment", fragment_base)
+    to_path2 = md_file.path.parent / fragment_base
+    if config.verbose:
+        log_item("to", to_path2)
+    File.copy(config=config, from_path=from_path, to_path=to_path2)
+    md_file.write(
+        "\n\n{% include-markdown \""
+        f"{fragment_base}"
+        "\" heading-offset=1 %}",
+        wrap_width=0
+    )

ekglib/maturity_model_parser/__init__.py

@@ -6,14 +6,17 @@
 from .loader import MaturityModelLoader  # noqa: F401
 from .exporter import GraphExporter  # noqa: F401
 from .markdown_generator import MaturityModelMarkdownGenerator  # noqa: F401
-from .__main__ import main, mkdocs_gen_files, mkdocs_gen_files2  # noqa: F401
+from .config import Config  # noqa: F401
+from .__main__ import main, run_with_config, run_with_args  # noqa: F401
 
 __all__ = [
+    'Config',
     'MaturityModelLoader',
     'MaturityModelMarkdownGenerator',
     'GraphExporter',
-    'mkdocs_gen_files',
     'main',
+    'run_with_config',
+    'run_with_args',
     'MaturityModelGraph',
     'MaturityModelPillar',
     'MaturityModelCapabilityArea',

ekglib/maturity_model_parser/__main__.py

@@ -1,54 +1,32 @@
 import argparse
 from pathlib import Path
 
+from ekglib.maturity_model_parser.config import Config
 from ekglib.maturity_model_parser.loader import MaturityModelLoader
 from ekglib.maturity_model_parser.markdown_generator import MaturityModelMarkdownGenerator
 
 
-def mkdocs_gen_files(model_root: Path, output_root: Path, docs_root: Path, fragments_root: Path):
-    loader = MaturityModelLoader(
-        verbose=True,
-        model_root=model_root,
-        docs_root=docs_root,
-        fragments_root=fragments_root
-    )
-    graph = loader.load()
-    generator = MaturityModelMarkdownGenerator(graph, model_name="EKG/MM", mkdocs=True, output_root=output_root)
-    generator.generate()
-    # exporter = GraphExporter(graph)
-    # return exporter.export(stream)
-    return 0
-
-
-def mkdocs_gen_files2(model_root: Path, output_root: Path, docs_root: Path, fragments_root: Path):
-    loader = MaturityModelLoader(
-        verbose=True,
-        model_root=model_root,
-        docs_root=docs_root,
-        fragments_root=fragments_root
-    )
+def run_with_config(config: Config) -> int:
+    loader = MaturityModelLoader(config)
     graph = loader.load()
-    generator = MaturityModelMarkdownGenerator(graph, model_name="EKG/MM", mkdocs=False, output_root=output_root)
+    generator = MaturityModelMarkdownGenerator(graph, config)
     generator.generate()
     # exporter = GraphExporter(graph)
     # return exporter.export(stream)
     return 0
 
 
-def runit(args) -> int:
-    loader = MaturityModelLoader(
+def run_with_args(args) -> int:
+    config = Config(
+        model_name=args.model,
         verbose=args.verbose,
+        mkdocs=False,
         model_root=Path(args.model_root),
         docs_root=Path(args.docs_root),
-        fragments_root=Path(args.fragments_root)
+        fragments_root=Path(args.fragments_root),
+        output_root=Path(args.output)
     )
-    graph = loader.load()
-    generator = MaturityModelMarkdownGenerator(graph, model_name=args.model, mkdocs=False,
-                                               output_root=Path(args.output))
-    generator.generate()
-    # exporter = GraphExporter(graph)
-    # return exporter.export(stream)
-    return 0
+    return run_with_config(config)
 
 
 def main():
@@ -68,7 +46,7 @@ def main():
     parser.add_argument('--output', help='The output directory', required=True)
     parser.add_argument('--model', help='The name of the model', default="EKG/MM")
 
-    return runit(parser.parse_args())
+    return run_with_args(parser.parse_args())
 
 
 if __name__ == "__main__":

ekglib/maturity_model_parser/capability.py

@@ -4,7 +4,8 @@
 from rdflib import RDFS, DCTERMS
 from rdflib.term import Node
 
-from .File import makedirs, File
+from .File import makedirs, File, copy_fragment
+from .config import Config
 from .markdown_document import MarkdownDocument
 from .pages_yaml import PagesYaml
 from ..namespace import MATURIY_MODEL
@@ -16,17 +17,25 @@ class MaturityModelCapability:
     class_label_plural: str = "Capabilities"
     class_iri = MATURIY_MODEL.Capability
 
-    def __init__(self, area: MaturityModelCapabilityArea, capability_node: Node, mkdocs: bool):
+    def __init__(
+            self,
+            area: MaturityModelCapabilityArea,
+            capability_node: Node,
+            capability_area_fragments_dir: Path,
+            config: Config
+    ):
         self.graph = area.graph
         self.area = area
-        self.capability_node = capability_node
-        self.mkdocs = mkdocs
+        self.node = capability_node
+        self.config = config
 
-        self.name = self.graph.name_for(self.capability_node, self.class_label)
-        self.number = self.graph.capability_number_for(self.capability_node, self.class_label)
-        self.local_name = self.graph.local_name_for(self.capability_node, self.class_label)
-        self.local_type_name = self.graph.local_type_name_for(self.capability_node, self.class_label)
+        self.name = self.graph.name_for(self.node, self.class_label)
+        self.number = self.graph.capability_number_for(self.node, self.class_label)
+        self.local_name = self.graph.local_name_for(self.node, self.class_label)
+        self.local_type_name = self.graph.local_type_name_for(self.node, self.class_label)
+        self.tag_line = self.graph.tag_line_for(self.node)
         self.full_dir = self.area.full_dir / self.local_type_name / self.local_name
+        self.fragments_dir = capability_area_fragments_dir / self.local_type_name / self.local_name
         self.md_file = None
         makedirs(self.full_dir, self.class_label)
 
@@ -36,6 +45,7 @@ def generate_markdown(self):
             "title": f"{self.number}. {self.name}"
         })
         self.generate_summary()
+        self.copy_fragments()
         self.md_file.create_md_file()
 
     def generate_link_from_area_to_capability(self):
@@ -44,9 +54,10 @@ def generate_link_from_area_to_capability(self):
             link=str(link), text=self.name
         ))
 
-    def summaries(self):
-        for rdfs_comment in self.graph.g.objects(self.capability_node, DCTERMS.description):
-            yield str(rdfs_comment).strip()
+    def copy_fragments(self):
+        copy_fragment(self.md_file, self.fragments_dir / 'background-and-intro.md', self.config)
+        copy_fragment(self.md_file, self.fragments_dir / 'dimensions.md', self.config)
+        copy_fragment(self.md_file, self.fragments_dir / 'levels.md', self.config)
 
     def generate_summary(self):
         # self.md_file.heading(2, "Summary")
@@ -57,8 +68,8 @@ def generate_summary(self):
             wrap_width=0
         )
         self.md_file.write("\n")
-        for summary in self.summaries():
-            self.md_file.write(summary, wrap_width=0)
+        self.graph.write_tag_line(self.md_file, self.node, self.class_label)
+        self.graph.write_description(self.md_file, self.node, self.class_label)
 
     @classmethod
     def generate_index_md(cls, area: MaturityModelCapabilityArea):
@@ -74,9 +85,8 @@ def generate_index_md(cls, area: MaturityModelCapabilityArea):
         )
         for capability in area.capabilities():
             md_file.heading(2, f"{capability.number}. [{capability.name}](./{capability.local_name}/)")
-            for summary in capability.summaries():
-                md_file.write(str(summary).strip(), wrap_width=0)
-                md_file.write("\n\n")
+            graph.write_tag_line(md_file, capability, MaturityModelCapability.class_label)
+            graph.write_description(md_file, capability, MaturityModelCapability.class_label)
 
         md_file.create_md_file()
 

ekglib/maturity_model_parser/capability_area.py

@@ -1,10 +1,11 @@
 import textwrap
 from pathlib import Path
 
-from rdflib import DCTERMS
+from rdflib import DCTERMS, RDFS
 from rdflib.term import Node
 
 from .File import makedirs, File
+from .config import Config
 from .markdown_document import MarkdownDocument
 from .pages_yaml import PagesYaml
 from .pillar import MaturityModelPillar
@@ -17,19 +18,27 @@ class MaturityModelCapabilityArea:
     class_label_plural: str = "Capability Areas"
     class_iri = MATURIY_MODEL.CapabilityArea
 
-    def __init__(self, pillar: MaturityModelPillar, area_node: Node, mkdocs: bool):
+    def __init__(
+            self,
+            pillar: MaturityModelPillar,
+            area_node: Node,
+            pillar_fragments_dir: Path,
+            config: Config
+    ):
         self.md_file = None
         self.graph = pillar.graph
         self.pillar = pillar
-        self.area_node = area_node
-        self.mkdocs = mkdocs
+        self.node = area_node
+        self.config = config
         self._capabilities = list()
 
-        self.name = self.graph.name_for(self.area_node, self.class_label)
-        self.local_name = self.graph.local_name_for(self.area_node, self.class_label)
-        self.local_type_name = self.graph.local_type_name_for(self.area_node, self.class_label)
+        self.name = self.graph.name_for(self.node, self.class_label)
+        self.local_name = self.graph.local_name_for(self.node, self.class_label)
+        self.local_type_name = self.graph.local_type_name_for(self.node, self.class_label)
+        self.tag_line = self.graph.tag_line_for(self.node)
         self.full_dir = self.pillar.full_dir / self.local_type_name / self.local_name
         self.full_path = self.full_dir / 'index.md'
+        self.fragments_dir = pillar_fragments_dir / self.local_type_name / self.local_name
         makedirs(self.full_dir, self.class_label)
 
     def generate_markdown(self):
@@ -38,20 +47,22 @@ def generate_markdown(self):
         self.md_file = MarkdownDocument(path=self.full_path, metadata={
             'title': self.name
         })
-        self.summary()
-        self.md_file.heading(2, MaturityModelCapability.class_label_plural)
+        self.generate_summary()
         self.generate_capabilities()
         self.md_file.create_md_file()
 
-    def summary(self):
+    def generate_summary(self):
         # self.md_file.heading(2, "Summary")
-        self.md_file.new_paragraph(
+        self.md_file.write(
             f"The capability area _{self.name}_ is "
-            f"in the [_{self.pillar.name}_](../../index.md).\n"
+            f"in the [_{self.pillar.name}_](../../index.md).\n",
+            wrap_width=0
         )
-        self.md_file.write("\n")
-        for rdfs_comment in self.graph.g.objects(self.area_node, DCTERMS.description):
-            self.md_file.write(str(rdfs_comment).strip(), wrap_width=0)
+        self.generate_summary_short(self.md_file)
+
+    def generate_summary_short(self, md_file: MarkdownDocument):
+        self.graph.write_tag_line(md_file, self.node, self.class_label)
+        self.graph.write_description(md_file, self.node, self.class_label)
 
     def generate_link_from_pillar_to_capability_area(self):
         link = Path('.') / self.local_type_name / self.local_name / 'index.md'
@@ -60,7 +71,7 @@ def generate_link_from_pillar_to_capability_area(self):
         ))
 
     def capabiliy_nodes_unsorted(self):
-        for capability_node in self.graph.g.subjects(MATURIY_MODEL.inArea, self.area_node):
+        for capability_node in self.graph.g.subjects(MATURIY_MODEL.inArea, self.node):
             yield capability_node
 
     def sort_key(self, element):
@@ -79,7 +90,7 @@ def capability_nodes(self):
     def capabilities_non_cached(self):
         from .capability import MaturityModelCapability
         for capability_node in self.capability_nodes():
-            yield MaturityModelCapability(self, capability_node, self.mkdocs)
+            yield MaturityModelCapability(self, capability_node, self.fragments_dir, self.config)
 
     def capabilities(self):
         if len(self._capabilities) == 0:
@@ -88,6 +99,7 @@ def capabilities(self):
 
     def generate_capabilities(self):
         from .capability import MaturityModelCapability
+        self.md_file.heading(2, MaturityModelCapability.class_label_plural)
         MaturityModelCapability.generate_index_md(self)
         MaturityModelCapability.generate_pages_yaml(self)
         for capability in self.capabilities():
@@ -102,6 +114,10 @@ def generate_index_md(cls, pillar: MaturityModelPillar):
         md_file = MarkdownDocument(path=root / 'index.md', metadata={
             "title": f"{pillar.name} --- {cls.class_label_plural}"
         })
+        for area in pillar.capability_areas():
+            md_file.heading(2, area.name, area.local_name)
+            area.generate_summary_short(md_file)
+            md_file.write(f'\n\n[More info...]({area.local_name})\n\n')
         md_file.create_md_file()
 
     @classmethod

ekglib/maturity_model_parser/config.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+
+from ekglib.log.various import value_error
+
+
+class Config:
+
+    def __init__(
+            self,
+            model_name: str,
+            verbose: bool,
+            mkdocs: bool,
+            model_root: Path,
+            docs_root: Path,
+            output_root: Path,
+            fragments_root: Path
+    ):
+        self.model_name = model_name
+        self.verbose = verbose
+        self.mkdocs = mkdocs
+        self.model_root = model_root
+        self.docs_root = docs_root
+        self.output_root = output_root
+        self.fragments_root = fragments_root
+
+        if not self.model_root.is_dir():
+            raise value_error("{} is not a valid directory", self.model_root.name)
+        if not self.docs_root.is_dir():
+            raise value_error("{} is not a valid directory", self.docs_root.name)
+        if not self.fragments_root.is_dir():
+            raise value_error("{} is not a valid directory", self.fragments_root.name)