Ref macro (#5)

* Adding ref macro w unit test

* adding ref to jinja helper context docs

.metadock/content_schematics/jinja_helpers/global.yml

@@ -19,6 +19,24 @@ global:
         snippet_body:
           - debug($1)
 
+    ref:
+      docstring: |
+        Renders and inserts the content from a given generated document in a given Metadock project.
+      example: |
+        >>> from metadock.env import MetadockEnv
+        >>> from metadock.project import MetadockProject
+        >>> env = MetadockEnv().jinja_environment()
+        >>> project = MetadockProject()
+        >>> env.from_string("{{ ref('my_generated_document') }}").render()
+        'Rendered contents of my_generated_document'
+      source_file: metadock/env.py
+      method_name: metadock.env.MetadockEnv.ref
+      signature: "(self, document_name: str) -> str"
+      intellisense:
+        snippet_key: Reference generated document
+        snippet_body:
+          - ref($1)
+
   filters:
     chain:
       docstring: |

.metadock/generated_documents/README.html

@@ -312,6 +312,7 @@ <h4>Jinja macros</h4>
 <p>The following macros are available in the global namespace:</p>
 <ul>
 <li><code>debug</code></li>
+<li><code>ref</code></li>
 </ul>
 <details>
 <summary>
@@ -331,6 +332,11 @@ <h4>Jinja macros</h4>
 <td><pre>metadock.env.MetadockEnv.debug: (self, message: str) -&gt; None</pre></td>
 <td>Prints a debug message to stdout, and returns an empty string.<br/><br/><pre>&gt;&gt;&gt; from metadock.env import MetadockEnv<br>&gt;&gt;&gt; env = MetadockEnv().jinja_environment()<br>&gt;&gt;&gt; env.from_string(&quot;No changes!{{ debug('This is a debug message.') }}&quot;).render()<br>This is a debug message.<br>'No changes!'<br></pre></td>
 </tr>
+<tr>
+<td><pre>ref</pre></td>
+<td><pre>metadock.env.MetadockEnv.ref: (self, document_name: str) -&gt; str</pre></td>
+<td>Renders and inserts the content from a given generated document in a given Metadock project. <br/><br/><pre>&gt;&gt;&gt; from metadock.env import MetadockEnv<br>&gt;&gt;&gt; from metadock.project import MetadockProject<br>&gt;&gt;&gt; env = MetadockEnv().jinja_environment()<br>&gt;&gt;&gt; project = MetadockProject()<br>&gt;&gt;&gt; env.from_string(&quot;{{ ref('my_generated_document') }}&quot;).render()<br>'Rendered contents of my_generated_document'<br></pre></td>
+</tr>
 </tbody></table></details>
 <p><br><br></p>
 <h4>Jinja filters</h4>

.metadock/generated_documents/README.md

@@ -354,6 +354,7 @@ Jinja namespace for the global Metadock environment, including all global macros
 The following macros are available in the global namespace:
 
 - `debug`
+- `ref`
 
 <details>
 <summary>
@@ -363,6 +364,7 @@ The following macros are available in the global namespace:
 | <b>Macro</b> | <b>Signature</b> | <b>Doc</b> |
 | --- | --- | --- |
 | <pre>debug</pre> | <pre>metadock.env.MetadockEnv.debug: (self, message: str) -> None</pre> | Prints a debug message to stdout, and returns an empty string.<br/><br/><pre>>>> from metadock.env import MetadockEnv<br>>>> env = MetadockEnv().jinja_environment()<br>>>> env.from_string("No changes!{{ debug('This is a debug message.') }}").render()<br>This is a debug message.<br>'No changes!'<br></pre> |
+| <pre>ref</pre> | <pre>metadock.env.MetadockEnv.ref: (self, document_name: str) -> str</pre> | Renders and inserts the content from a given generated document in a given Metadock project. <br/><br/><pre>>>> from metadock.env import MetadockEnv<br>>>> from metadock.project import MetadockProject<br>>>> env = MetadockEnv().jinja_environment()<br>>>> project = MetadockProject()<br>>>> env.from_string("{{ ref('my_generated_document') }}").render()<br>'Rendered contents of my_generated_document'<br></pre> |
 
 </details>
 

.metadock/generated_documents/jinja-md.code-snippets

@@ -10,6 +10,15 @@
         ],
         "description": "Debug message macro"
     },
+
+    "(macro) Reference generated document": {
+        "scope": "jinja-md,md",
+        "prefix": "ref",
+        "body": [
+            "ref($1)"
+        ],
+        "description": "Reference generated document macro"
+    },
     "(filter) Chain iterables": {
         "scope": "jinja-md,md",
         "prefix": "chain",

.vscode/jinja-md.code-snippets

@@ -10,6 +10,15 @@
         ],
         "description": "Debug message macro"
     },
+
+    "(macro) Reference generated document": {
+        "scope": "jinja-md,md",
+        "prefix": "ref",
+        "body": [
+            "ref($1)"
+        ],
+        "description": "Reference generated document macro"
+    },
     "(filter) Chain iterables": {
         "scope": "jinja-md,md",
         "prefix": "chain",

README.md

@@ -354,6 +354,7 @@ Jinja namespace for the global Metadock environment, including all global macros
 The following macros are available in the global namespace:
 
 - `debug`
+- `ref`
 
 <details>
 <summary>
@@ -363,6 +364,7 @@ The following macros are available in the global namespace:
 | <b>Macro</b> | <b>Signature</b> | <b>Doc</b> |
 | --- | --- | --- |
 | <pre>debug</pre> | <pre>metadock.env.MetadockEnv.debug: (self, message: str) -> None</pre> | Prints a debug message to stdout, and returns an empty string.<br/><br/><pre>>>> from metadock.env import MetadockEnv<br>>>> env = MetadockEnv().jinja_environment()<br>>>> env.from_string("No changes!{{ debug('This is a debug message.') }}").render()<br>This is a debug message.<br>'No changes!'<br></pre> |
+| <pre>ref</pre> | <pre>metadock.env.MetadockEnv.ref: (self, document_name: str) -> str</pre> | Renders and inserts the content from a given generated document in a given Metadock project. <br/><br/><pre>>>> from metadock.env import MetadockEnv<br>>>> from metadock.project import MetadockProject<br>>>> env = MetadockEnv().jinja_environment()<br>>>> project = MetadockProject()<br>>>> env.from_string("{{ ref('my_generated_document') }}").render()<br>'Rendered contents of my_generated_document'<br></pre> |
 
 </details>
 

metadock/engine.py

@@ -146,7 +146,7 @@ def __init__(self, directory: Path | str):
             directory (Path | str): .metadock directory to open
         """
         self.directory = Path(directory)
-        self.environment = MetadockEnv().jinja_environment()
+        self.environment = MetadockEnv(self).jinja_environment()
         # self.environment.globals |= env_dict["exports"]
         # self.environment.globals |= env_dict["namespaces"]
         # self.environment.filters |= env_dict["filters"]

metadock/env.py

@@ -32,10 +32,19 @@ class MetadockNamespace(abc.ABC):
         filters (list[str]): List of filter names to be exported as attributes of this namespace.
     """
 
+    project: Any  # MetadockProject
     exports: list[str] = []
     namespaces: list[str] = []
     filters: list[Annotated[str, "implementation ends with('_filter')"]] = []
 
+    def __init__(self, project: Any):
+        """Common constructor for types of MetadockNamespace.
+
+        Args:
+            project (MetadockProject): The Metadock project which provides project context to this namespace.
+        """
+        self.project = project
+
     def dict(self) -> dict[Literal["exports", "namespaces", "filters"], dict[str, Any]]:
         """Produces a dictionary of the exports, namespaces, and filters of this namespace in a fashion which can be
         consumed by a Jinja2 environment.
@@ -174,7 +183,7 @@ def tablehead(self, *header_cells: str, bold: bool = False) -> str:
         """
         _pipe_escaped_cells = tuple(map(lambda cell: cell.replace("|", "\\|"), header_cells))
         if bold:
-            _pipe_escaped_cells = tuple(MetadockHtmlNamespace().bold(cell) for cell in _pipe_escaped_cells)
+            _pipe_escaped_cells = tuple(MetadockHtmlNamespace(self.project).bold(cell) for cell in _pipe_escaped_cells)
         return self.tablerow(*_pipe_escaped_cells) + "\n" + self.tablerow(*(["---"] * len(_pipe_escaped_cells)))
 
     def convert_filter(self, md_content: str) -> str:
@@ -337,6 +346,7 @@ class MetadockEnv(MetadockNamespace):
     **Macros**:
 
         debug
+        ref
 
     **Namespaces**:
 
@@ -353,12 +363,25 @@ class MetadockEnv(MetadockNamespace):
         zip
     """
 
-    md = MetadockMdNamespace()
-    html = MetadockHtmlNamespace()
-    exports = ["debug"]
+    project: Any  # MetadockProject
+    md: MetadockMdNamespace
+    html: MetadockHtmlNamespace
+    exports = ["debug", "ref"]
     namespaces = ["html", "md"]
     filters = ["chain", "inline", "with_prefix", "with_suffix", "wrap", "zip"]
 
+    def __init__(self, project: Any):
+        super().__init__(project)
+        self.md = MetadockMdNamespace(project)
+        self.html = MetadockHtmlNamespace(project)
+
+    def ref(self, document_name: str) -> str:
+        """Renders and inserts the content from a given generated document in a given Metadock project."""
+        gen_docs = self.project.build([document_name])
+        gen_doc = gen_docs.generated_documents[0]
+        generated_path = gen_doc.path
+        return generated_path.read_text()
+
     def debug(self, message: str) -> Literal[""]:
         """Prints a debug message to stdout, and returns an empty string."""
         print(message)

tests/test_env.py

@@ -398,3 +398,50 @@ def test_env__wrap(empty_metadock_project_dir):
     metadock.build()
 
     assert (project_dir / "generated_documents" / "example1.md").read_text() == ("""||line a, line b, line c||""")
+
+
+def test_env__ref(empty_metadock_project_dir):
+    project_dir = empty_metadock_project_dir
+    (project_dir / "templated_documents" / "root_document_template.md").write_text(
+        """`RootDocument!`
+Context name = {{ name }}"""
+    )
+    (project_dir / "content_schematics" / "root_doc.yml").write_text(
+        """
+        content_schematics:
+          - name: root_document
+            template: root_document_template.md
+            target_formats: [ md ]
+            context: 
+              name: David
+        """
+    )
+    (project_dir / "templated_documents" / "simple.md").write_text(
+        """Root:
+    {{ ref("root_document") | indent(4) }}
+Context name = {{ name }}"""
+    )
+    (project_dir / "content_schematics" / "schematic1.yml").write_text(
+        """
+        content_schematics:
+          - name: simple
+            template: simple.md
+            target_formats: [ md ]
+            context:
+              name: Nothing.
+        """
+    )
+
+    metadock = MetadockProject(project_dir)
+    metadock.build()
+
+    assert (project_dir / "generated_documents" / "root_document.md").read_text() == (
+        """`RootDocument!`
+Context name = David"""
+    )
+    assert (project_dir / "generated_documents" / "simple.md").read_text() == (
+        """Root:
+    `RootDocument!`
+    Context name = David
+Context name = Nothing."""
+    )