Update documentation

Author: github-actions[bot]

main/.doctrees/developers_guide/api.doctree

@@ -85,7 +85,6 @@
   <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
 <span></span><span class="kn">import</span><span class="w"> </span><span class="nn">re</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">collections</span><span class="w"> </span><span class="kn">import</span> <span class="n">defaultdict</span>
-<span class="kn">from</span><span class="w"> </span><span class="nn">importlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">resources</span> <span class="k">as</span> <span class="n">importlib_resources</span>
 
 <span class="kn">from</span><span class="w"> </span><span class="nn">lxml</span><span class="w"> </span><span class="kn">import</span> <span class="n">etree</span>
 
@@ -195,13 +194,13 @@ <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
     <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">)</span>
 
     <span class="k">if</span> <span class="n">e3sm_hdf5_netcdf_modules</span><span class="p">:</span>
-        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">%- i</span><span class="s1">f e3sm_hdf5_netcdf %}&#39;</span><span class="p">)</span>
+        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">% i</span><span class="s1">f e3sm_hdf5_netcdf %}&#39;</span><span class="p">)</span>
         <span class="n">script_lines</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span>
             <span class="n">_convert_module_commands_to_script_lines</span><span class="p">(</span>
                 <span class="n">e3sm_hdf5_netcdf_modules</span><span class="p">,</span> <span class="n">shell_type</span>
             <span class="p">)</span>
         <span class="p">)</span>
-        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">%- e</span><span class="s1">ndif %}&#39;</span><span class="p">)</span>
+        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">% e</span><span class="s1">ndif %}&#39;</span><span class="p">)</span>
         <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">)</span>
 
     <span class="n">script_lines</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="n">_convert_env_vars_to_script_lines</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">shell_type</span><span class="p">))</span>
@@ -215,7 +214,7 @@ <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
 <div class="viewcode-block" id="extract_spack_from_config_machines">
 <a class="viewcode-back" href="../../../developers_guide/generated/mache.spack.extract_spack_from_config_machines.html#mache.spack.extract_spack_from_config_machines">[docs]</a>
 <span class="k">def</span><span class="w"> </span><span class="nf">extract_spack_from_config_machines</span><span class="p">(</span>
-    <span class="n">machine</span><span class="p">,</span> <span class="n">compiler</span><span class="p">,</span> <span class="n">mpilib</span><span class="p">,</span> <span class="n">shell</span><span class="p">,</span> <span class="n">output</span><span class="o">=</span><span class="kc">None</span>
+    <span class="n">machine</span><span class="p">,</span> <span class="n">compiler</span><span class="p">,</span> <span class="n">mpilib</span><span class="p">,</span> <span class="n">shell</span><span class="p">,</span> <span class="n">output</span>
 <span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Extract machine configuration from XML and write it to a shell script.</span>
@@ -230,18 +229,10 @@ <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
 <span class="sd">        MPI library name.</span>
 <span class="sd">    shell : str</span>
 <span class="sd">        Shell script type (&#39;sh&#39; or &#39;csh&#39;).</span>
-<span class="sd">    output : str, optional</span>
+<span class="sd">    output : str</span>
 <span class="sd">        Output file to write the shell script.</span>
-
-<span class="sd">    Returns</span>
-<span class="sd">    -------</span>
-<span class="sd">    script: str</span>
-<span class="sd">        The generated shell script as a string.</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="n">config_filename</span> <span class="o">=</span> <span class="p">(</span>
-        <span class="n">importlib_resources</span><span class="o">.</span><span class="n">files</span><span class="p">(</span><span class="s1">&#39;mache.cime_machine_config&#39;</span><span class="p">)</span>
-        <span class="o">/</span> <span class="s1">&#39;config_machines.xml&#39;</span>
-    <span class="p">)</span>
+    <span class="n">config_filename</span> <span class="o">=</span> <span class="s1">&#39;mache/cime_machine_config/config_machines.xml&#39;</span>
 
     <span class="n">config</span> <span class="o">=</span> <span class="n">extract_machine_config</span><span class="p">(</span><span class="n">config_filename</span><span class="p">,</span> <span class="n">machine</span><span class="p">,</span> <span class="n">compiler</span><span class="p">,</span> <span class="n">mpilib</span><span class="p">)</span>
     <span class="k">if</span> <span class="n">config</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
@@ -251,11 +242,8 @@ <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
         <span class="p">)</span>
 
     <span class="n">script</span> <span class="o">=</span> <span class="n">config_to_shell_script</span><span class="p">(</span><span class="n">config</span><span class="p">,</span> <span class="n">shell</span><span class="p">)</span>
-    <span class="k">if</span> <span class="n">output</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
-        <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">output</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
-            <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">script</span><span class="p">)</span>
-
-    <span class="k">return</span> <span class="n">script</span></div>
+    <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">output</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>
+        <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">script</span><span class="p">)</span></div>
 
 
 
@@ -355,13 +343,13 @@ <h1>Source code for mache.spack.config_machines</h1><div class="highlight"><pre>
     <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;&#39;</span><span class="p">)</span>
 
     <span class="k">if</span> <span class="n">e3sm_hdf5_netcdf_env_vars</span><span class="p">:</span>
-        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">%- i</span><span class="s1">f e3sm_hdf5_netcdf %}&#39;</span><span class="p">)</span>
+        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">% i</span><span class="s1">f e3sm_hdf5_netcdf %}&#39;</span><span class="p">)</span>
         <span class="k">for</span> <span class="n">name</span><span class="p">,</span> <span class="n">value</span> <span class="ow">in</span> <span class="n">e3sm_hdf5_netcdf_env_vars</span><span class="p">:</span>
             <span class="k">if</span> <span class="n">shell_type</span> <span class="o">==</span> <span class="s1">&#39;sh&#39;</span><span class="p">:</span>
                 <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;export </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s1">=&quot;</span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s1">&quot;&#39;</span><span class="p">)</span>
             <span class="k">elif</span> <span class="n">shell_type</span> <span class="o">==</span> <span class="s1">&#39;csh&#39;</span><span class="p">:</span>
                 <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="sa">f</span><span class="s1">&#39;setenv </span><span class="si">{</span><span class="n">name</span><span class="si">}</span><span class="s1"> &quot;</span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s1">&quot;&#39;</span><span class="p">)</span>
-        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">%- e</span><span class="s1">ndif %}&#39;</span><span class="p">)</span>
+        <span class="n">script_lines</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s1">&#39;{</span><span class="si">% e</span><span class="s1">ndif %}&#39;</span><span class="p">)</span>
 
     <span class="k">return</span> <span class="n">script_lines</span>
 </pre></div>

main/.doctrees/developers_guide/generated/mache.spack.extract_spack_from_config_machines.doctree

@@ -90,7 +90,7 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
 <span class="kn">from</span><span class="w"> </span><span class="nn">jinja2</span><span class="w"> </span><span class="kn">import</span> <span class="n">Template</span>
 
 <span class="kn">from</span><span class="w"> </span><span class="nn">mache.machine_info</span><span class="w"> </span><span class="kn">import</span> <span class="n">MachineInfo</span><span class="p">,</span> <span class="n">discover_machine</span>
-<span class="kn">from</span><span class="w"> </span><span class="nn">mache.spack.shared</span><span class="w"> </span><span class="kn">import</span> <span class="n">_get_yaml_data</span>
+<span class="kn">from</span><span class="w"> </span><span class="nn">mache.spack.shared</span><span class="w"> </span><span class="kn">import</span> <span class="n">_get_modules</span><span class="p">,</span> <span class="n">_get_yaml_data</span>
 <span class="kn">from</span><span class="w"> </span><span class="nn">mache.version</span><span class="w"> </span><span class="kn">import</span> <span class="n">__version__</span>
 
 
@@ -176,6 +176,12 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
     <span class="k">if</span> <span class="n">config_file</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
         <span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="n">config_file</span><span class="p">)</span>
 
+    <span class="n">section</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">&#39;spack&#39;</span><span class="p">]</span>
+
+    <span class="n">with_modules</span> <span class="o">=</span> <span class="n">section</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">&#39;modules_before&#39;</span><span class="p">)</span> <span class="ow">or</span> <span class="n">section</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span>
+        <span class="s1">&#39;modules_after&#39;</span>
+    <span class="p">)</span>
+
     <span class="n">yaml_data</span> <span class="o">=</span> <span class="n">_get_yaml_data</span><span class="p">(</span>
         <span class="n">machine</span><span class="p">,</span>
         <span class="n">compiler</span><span class="p">,</span>
@@ -190,7 +196,11 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
     <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">yaml_filename</span><span class="p">,</span> <span class="s1">&#39;w&#39;</span><span class="p">)</span> <span class="k">as</span> <span class="n">handle</span><span class="p">:</span>
         <span class="n">handle</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">yaml_data</span><span class="p">)</span>
 
-    <span class="n">modules</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>
+    <span class="k">if</span> <span class="n">with_modules</span><span class="p">:</span>
+        <span class="n">mods</span> <span class="o">=</span> <span class="n">_get_modules</span><span class="p">(</span><span class="n">yaml_data</span><span class="p">)</span>
+        <span class="n">modules</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;module purge</span><span class="se">\n</span><span class="si">{</span><span class="n">mods</span><span class="si">}</span><span class="s1">&#39;</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="n">modules</span> <span class="o">=</span> <span class="s1">&#39;&#39;</span>
 
     <span class="k">for</span> <span class="n">shell_filename</span> <span class="ow">in</span> <span class="p">[</span><span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">machine</span><span class="si">}</span><span class="s1">.sh&#39;</span><span class="p">,</span> <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">machine</span><span class="si">}</span><span class="s1">_</span><span class="si">{</span><span class="n">compiler</span><span class="si">}</span><span class="s1">_</span><span class="si">{</span><span class="n">mpi</span><span class="si">}</span><span class="s1">.sh&#39;</span><span class="p">]:</span>
         <span class="c1"># load modules, etc. for this machine</span>
@@ -254,6 +264,7 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
     <span class="n">shell</span><span class="p">,</span>
     <span class="n">include_e3sm_lapack</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
     <span class="n">include_e3sm_hdf5_netcdf</span><span class="o">=</span><span class="kc">False</span><span class="p">,</span>
+    <span class="n">yaml_template</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
 <span class="p">):</span>
 <span class="w">    </span><span class="sd">&quot;&quot;&quot;</span>
 <span class="sd">    Get the non-spack modules, environment variables and compiler names for a</span>
@@ -282,6 +293,11 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
 <span class="sd">        Whether to include the same hdf5, netcdf-c, netcdf-fortran and pnetcdf</span>
 <span class="sd">        as used in E3SM</span>
 
+<span class="sd">    yaml_template : str, optional</span>
+<span class="sd">        A jinja template for a yaml file to be used for the environment instead</span>
+<span class="sd">        of the mache template.  This allows you to use compilers and other</span>
+<span class="sd">        modules that differ from E3SM.</span>
+
 <span class="sd">    Returns</span>
 <span class="sd">    -------</span>
 <span class="sd">    mpicc : str</span>
@@ -310,10 +326,27 @@ <h1>Source code for mache.spack.env</h1><div class="highlight"><pre>
     <span class="k">if</span> <span class="n">config</span><span class="o">.</span><span class="n">has_section</span><span class="p">(</span><span class="s1">&#39;spack&#39;</span><span class="p">):</span>
         <span class="n">section</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">&#39;spack&#39;</span><span class="p">]</span>
 
+        <span class="n">with_modules</span> <span class="o">=</span> <span class="n">section</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span>
+            <span class="s1">&#39;modules_before&#39;</span>
+        <span class="p">)</span> <span class="ow">or</span> <span class="n">section</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">&#39;modules_after&#39;</span><span class="p">)</span>
         <span class="k">if</span> <span class="n">config</span><span class="o">.</span><span class="n">has_option</span><span class="p">(</span><span class="s1">&#39;spack&#39;</span><span class="p">,</span> <span class="s1">&#39;cray_compilers&#39;</span><span class="p">):</span>
             <span class="n">cray_compilers</span> <span class="o">=</span> <span class="n">section</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">&#39;cray_compilers&#39;</span><span class="p">)</span>
+    <span class="k">else</span><span class="p">:</span>
+        <span class="n">with_modules</span> <span class="o">=</span> <span class="kc">False</span>
 
     <span class="n">mod_env_commands</span> <span class="o">=</span> <span class="s1">&#39;module purge</span><span class="se">\n</span><span class="s1">&#39;</span>
+    <span class="k">if</span> <span class="n">with_modules</span><span class="p">:</span>
+        <span class="n">yaml_data</span> <span class="o">=</span> <span class="n">_get_yaml_data</span><span class="p">(</span>
+            <span class="n">machine</span><span class="p">,</span>
+            <span class="n">compiler</span><span class="p">,</span>
+            <span class="n">mpi</span><span class="p">,</span>
+            <span class="n">include_e3sm_lapack</span><span class="p">,</span>
+            <span class="n">include_e3sm_hdf5_netcdf</span><span class="p">,</span>
+            <span class="n">specs</span><span class="o">=</span><span class="p">[],</span>
+            <span class="n">yaml_template</span><span class="o">=</span><span class="n">yaml_template</span><span class="p">,</span>
+        <span class="p">)</span>
+        <span class="n">mods</span> <span class="o">=</span> <span class="n">_get_modules</span><span class="p">(</span><span class="n">yaml_data</span><span class="p">)</span>
+        <span class="n">mod_env_commands</span> <span class="o">=</span> <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">mod_env_commands</span><span class="si">}</span><span class="se">\n</span><span class="si">{</span><span class="n">mods</span><span class="si">}</span><span class="se">\n</span><span class="s1">&#39;</span>
 
     <span class="k">for</span> <span class="n">shell_filename</span> <span class="ow">in</span> <span class="p">[</span>
         <span class="sa">f</span><span class="s1">&#39;</span><span class="si">{</span><span class="n">machine</span><span class="si">}</span><span class="s1">.</span><span class="si">{</span><span class="n">shell</span><span class="si">}</span><span class="s1">&#39;</span><span class="p">,</span>