Merge pull request #253 from snek5000/doc-template

New API for templates to simplify solver code (+ documentation).

CHANGELOG.md

@@ -28,7 +28,12 @@ Security in case of vulnerabilities.
 
 <!-- (changelog/unreleased)= -->
 
-<!-- ## [Unreleased] -->
+## [Unreleased]
+
+### Added
+
+- {func}`snek5000.output.base.Output.post_init_create_additional_source_files` and
+  {func}`snek5000.resources.get_base_templates`.
 
 ## [0.9.0rc0]
 
@@ -357,8 +362,6 @@ lists are a very incomplete lists of the additions, changes and deprecations.
 - Python packaging
 - Sphinx + Doxygen + Breathe documentation
 
-<!-- [unreleased]: https://github.com/snek5000/snek5000/compare/0.8.0...HEAD -->
-
 [0.0.1]: https://github.com/snek5000/snek5000/releases/tag/0.0.1
 [0.1.0]: https://github.com/snek5000/snek5000/compare/0.0.1...0.1.0
 [0.1.1]: https://github.com/snek5000/snek5000/compare/0.1.0...0.1.1
@@ -377,3 +380,4 @@ lists are a very incomplete lists of the additions, changes and deprecations.
 [0.8.0]: https://github.com/snek5000/snek5000/compare/0.7.0b0...0.8.0
 [0.9.0rc0]: https://github.com/snek5000/snek5000/compare/0.8.0...0.9.0rc0
 [@paugier]: https://github.com/paugier
+[unreleased]: https://github.com/snek5000/snek5000/compare/0.8.0...HEAD

docs/examples/snek5000-canonical/src/snek5000_canonical/output.py

@@ -1,10 +1,15 @@
-from snek5000_canonical.templates import box, makefile_usr, size
-
-from snek5000 import mpi
 from snek5000.output.base import Output as OutputBase
+from snek5000.resources import get_base_templates
+
+box, makefile_usr, size = get_base_templates()
 
 
 class OutputCanonical(OutputBase):
+
+    template_box = box
+    template_makefile_usr = makefile_usr
+    template_size = size
+
     @classmethod
     def _set_info_solver_classes(cls, classes):
         """Set the the classes for info_solver.classes.Output
@@ -50,14 +55,5 @@ def makefile_usr_sources(self):
         #     ],
         # }
 
-    def post_init(self):
-        super().post_init()
-
-        # Write additional source files to compile the simulation
-        if mpi.rank == 0 and self._has_to_save and self.sim.params.NEW_DIR_RESULTS:
-            self.write_box(box)
-            self.write_size(size)
-            self.write_makefile_usr(makefile_usr)
-
 
 Output = OutputCanonical

docs/examples/snek5000-tgv/src/snek5000_tgv/output.py

@@ -1,10 +1,14 @@
-from snek5000_tgv.templates import box, makefile_usr, size
-
-from snek5000 import mpi
 from snek5000.output.base import Output as OutputBase
+from snek5000.resources import get_base_templates
+
+box, makefile_usr, size = get_base_templates()
 
 
 class OutputTGV(OutputBase):
+    template_box = box
+    template_makefile_usr = makefile_usr
+    template_size = size
+
     @property
     def makefile_usr_sources(self):
         """
@@ -13,15 +17,6 @@ def makefile_usr_sources(self):
         """
         return {}
 
-    def post_init(self):
-        super().post_init()
-
-        # Write additional source files to compile the simulation
-        if mpi.rank == 0 and self._has_to_save and self.sim.params.NEW_DIR_RESULTS:
-            self.write_box(box)
-            self.write_size(size)
-            self.write_makefile_usr(makefile_usr)
-
     @classmethod
     def _set_info_solver_classes(cls, classes):
         """Set the the classes for info_solver.classes.Output"""

docs/how-to/index.md

@@ -15,6 +15,7 @@ history_points.md
 rebuild-nek.md
 export-sans-snek5000.myst.md
 archive-simulation-data.md
+templates.md
 ```
 
 ## For developer of Snek5000 solvers

docs/how-to/templates.md

@@ -0,0 +1,37 @@
+# How to Jinja templates
+
+Three files needed for Nek5000 are produced by Snek5000 through [Jinja] templates:
+`<case name>.box`, `SIZE` and `makefile_usr.inc`. As a Nek5000 user, you might want to
+understand how these important files are produced, so let us explain by diving into the
+code:
+
+- These files are produced by the methods:
+
+  - {func}`snek5000.output.base.Output.write_box` (which calls
+    {func}`snek5000.operators.Operators.write_box`),
+  - {func}`snek5000.output.base.Output.write_size` (which calls
+    {func}`snek5000.operators.Operators.write_size`) and
+  - {func}`snek5000.output.base.Output.write_makefile_usr`.
+
+- These methods are called in a method
+  {func}`snek5000.output.base.Output.post_init_create_additional_source_files` which
+  uses the class attributes `template_box`, `template_size` and `template_makefile_usr`.
+  These attributes are defined in the solvers, for example for `snek5000-tgv` in the file
+  `snek5000_tgv.output`:
+
+  ```{eval-rst}
+  .. literalinclude:: ../examples/snek5000-tgv/src/snek5000_tgv/output.py
+  ```
+
+  ```{note}
+  With this mechanism, the template files can be obtained from a simulation
+  object with `sim.output.template_box.filename`.
+  ```
+
+- Some base template files are in the subpackage {mod}`snek5000.resources`. These files
+  are general enough so that they can be used directly by most solvers (for example we
+  saw that `snek5000-tgv` uses {func}`snek5000.resources.get_base_templates`). However,
+  it is also possible to use other templates. For example, in `snek5000-cbox`,
+  [Jinja inheritance is used to extend the template for the `SIZE` file](https://github.com/snek5000/snek5000-cbox/tree/main/src/snek5000_cbox/templates).
+
+[jinja]: https://jinja.palletsprojects.com

docs/tuto_packaging.rst

@@ -82,6 +82,12 @@ src/snek5000_canonical/output.py
 
 .. literalinclude:: examples/snek5000-canonical/src/snek5000_canonical/output.py
 
+.. note::
+
+   One can also define your own Jinja templates or re-purpose them from
+   :mod:`snek5000.resources`. See our `How to page on templates
+   <./how-to/templates.html>`__.
+
 src/snek5000_canonical/phys_fields.py
 -------------------------------------
 
@@ -91,14 +97,6 @@ case.
 
 .. literalinclude:: examples/snek5000-canonical/src/snek5000_canonical/phys_fields.py
 
-src/snek5000_canonical/templates/__init__.py
---------------------------------------------
-
-Define your own Jinja templates or re-purpose them from :mod:`snek5000.resources`
-if you may.
-
-.. literalinclude:: examples/snek5000-canonical/src/snek5000_canonical/templates/__init__.py
-
 .. _user_snakefile:
 
 src/snek5000_canonical/Snakefile

src/snek5000/output/base.py

@@ -769,6 +769,18 @@ def post_init(self):
             self.copy(self.path_run)
             config = self.write_snakemake_config()
             self.build_nek5000(config)
+            self.post_init_create_additional_source_files()
+
+    def post_init_create_additional_source_files(self):
+        """Create the .box, SIZE and makefile_usr files from their template"""
+        for name in ("box", "size", "makefile_usr"):
+            try:
+                template = getattr(self, f"template_{name}")
+            except AttributeError:
+                pass
+            else:
+                if template is not None:
+                    getattr(self, f"write_{name}")(template)
 
     def _save_info_solver_params_xml(self, replace=False):
         """Saves the par file, along with ``params_simul.xml`` and

src/snek5000/resources/__init__.py

@@ -42,12 +42,6 @@
 .. literalinclude:: ../../src/snek5000/resources/box.j2
     :language: jinja
 
-- ``compile.sh.j2``: See also
-    :any:`snek5000.output.base.Output.write_compile_sh`.
-
-.. literalinclude:: ../../src/snek5000/resources/compile.sh.j2
-    :language: jinja
-
 - ``makefile_usr.inc.j2``: See also
     :any:`snek5000.output.base.Output.write_makefile_usr`.
 
@@ -62,4 +56,28 @@
 .. literalinclude:: ../../src/snek5000/resources/SIZE.j2
     :language: jinja
 
+- ``compile.sh.j2``: See also
+    :any:`snek5000.output.base.Output.write_compile_sh`.
+
+.. literalinclude:: ../../src/snek5000/resources/compile.sh.j2
+    :language: jinja
+
 """
+
+
+import jinja2
+
+
+def get_base_templates():
+    """Get templates (box, makefile_usr and size) from ``snek5000.resources``."""
+    env = jinja2.Environment(
+        loader=jinja2.PackageLoader("snek5000", "resources"),
+        undefined=jinja2.StrictUndefined,
+        autoescape=True,
+    )
+
+    box = env.get_template("box.j2")
+    makefile_usr = env.get_template("makefile_usr.inc.j2")
+    size = env.get_template("SIZE.j2")
+
+    return box, makefile_usr, size