Rework runtime parameter docs

sphinx_docs/rp.py

@@ -3,6 +3,7 @@
 import os
 import sys
 import textwrap
+import itertools
 
 MAIN_HEADER = """
 +---------------------------------------+---------------------------------------------------------+------------------------------+
@@ -28,23 +29,39 @@ def __init__(self):
         self.default = ""
         self.description = []
         self.category = ""
-
-    def value(self):
-        """ the value is what we sort based on """
-        return self.category + "." + self.var
-
-    def __lt__(self, other):
-        return self.value() < other.value()
+        self.namespace = ""
+
+
+def pretty_category(path):
+    if "/" not in path:
+        # global parameters for a given top-level directory
+        return ""
+    # remove the top-most directory
+    subdir = path.partition('/')[2]
+    if path.startswith("networks/"):
+        return f"NETWORK_DIR={subdir}"
+    if path.startswith("EOS/"):
+        return f"EOS_DIR={subdir}"
+    if path.startswith("conductivity/"):
+        return f"CONDUCTIVITY_DIR={subdir}"
+    if path.startswith("integration/"):
+        return f"INTEGRATOR_DIR={subdir}"
+    return path
 
 
 def make_rest_table(param_files):
 
     params_list = []
 
+    microphysics_home = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
     for pf in param_files:
 
         # each file is a category
-        category = os.path.basename(os.path.dirname(pf))
+        category = pretty_category(os.path.relpath(os.path.dirname(os.path.abspath(pf)), microphysics_home))
+
+        # default namespace is empty
+        namespace = ""
 
         # open the file
         try:
@@ -72,8 +89,12 @@ def make_rest_table(param_files):
                 continue
 
             if line.startswith("@"):
-                line = f.readline()
-                continue
+                # this is a command -- we only know namespace
+                fields = line.split()
+                if fields[0].startswith("@namespace"):
+                    namespace = fields[1].strip()
+                    line = f.readline()
+                    continue
 
             # find the description
             if line.startswith("#"):
@@ -90,6 +111,7 @@ def make_rest_table(param_files):
                 current_param.default = line_list[2]
                 current_param.description = descr
                 current_param.category = category
+                current_param.namespace = namespace
 
                 descr = r""
 
@@ -99,34 +121,52 @@ def make_rest_table(param_files):
             line = f.readline()
 
 
-    categories = {q.category for q in params_list}
+    def by_namespace(p):
+        return p.namespace
+
+    def by_category(p):
+        return p.category
+
+    print("Parameters by Namespace")
+    print("=======================")
+
+    # group by namespace first (roughly corresponds to top-level directory)
+
+    for nm, group in itertools.groupby(sorted(params_list, key=by_namespace), key=by_namespace):
+
+        # print the namespace
 
-    for c in sorted(categories):
+        if nm:
+            nm_formatted = f"namespace: ``{nm}``"
+        else:
+            nm_formatted = "namespace: none"
+        nmlen = len(nm_formatted)
+        print(nm_formatted)
+        print(nmlen*"-" + "\n")
 
-        # print the heading
+        for c, params in itertools.groupby(sorted(group, key=by_category), key=by_category):
 
-        params = [q for q in params_list if q.category == c]
+            # print the heading
 
-        clen = len(c)
-        print(c)
-        print(clen*"=" + "\n")
+            if c:
+                print(f"**{c}:**\n")
 
-        print(MAIN_HEADER.strip())
+            print(MAIN_HEADER.strip())
 
-        for p in params:
-            desc = list(textwrap.wrap(p.description.strip(), WRAP_LEN))
-            if not desc:
-                desc = [""]
+            for p in params:
+                desc = list(textwrap.wrap(p.description.strip(), WRAP_LEN))
+                if not desc:
+                    desc = [""]
 
-            for n, d in enumerate(desc):
-                if n == 0:
-                    print(ENTRY.format("``"+p.var+"``", d, p.default).strip())
-                else:
-                    print(ENTRY.format(" ", d, " ").strip())
+                for n, d in enumerate(desc):
+                    if n == 0:
+                        print(ENTRY.format("``"+p.var+"``", d, p.default).strip())
+                    else:
+                        print(ENTRY.format(" ", d, " ").strip())
 
-            print(SEPARATOR.strip())
+                print(SEPARATOR.strip())
 
-        print("\n\n")
+            print("\n\n")
 
 def main():
 

sphinx_docs/source/integrators.rst

@@ -454,7 +454,7 @@ Overriding Parameter Defaults on a Network-by-Network Basis
 Any network can override or add to any of the existing runtime
 parameters by creating a ``_parameters`` file in the network directory
 (e.g., ``networks/triple_alpha_plus_cago/_parameters``). As noted in
-Chapter [chapter:parameters], the fourth column in the ``_parameter``
+:doc:`rp_intro`, the fourth column in the ``_parameter``
 file definition is the *priority*. When a duplicate parameter is
 encountered by the scripts writing the runtime parameter header files, the value
 of the parameter with the highest priority is used. So picking a large

sphinx_docs/source/nse.rst

@@ -176,8 +176,6 @@ We determine is a zone is in NSE according to:
 
 * :math:`X(\isotm{He}{4}) + X(\isotm{Cr}{48}) + X(\isotm{Fe}{52}) + X(\isotm{Fe}{54}) + X(\isotm{Ni}{56})` > ``He_Fe_nse``
 
-.. _self_consistent_nse:
-
 
 NSE table ranges
 ----------------
@@ -190,6 +188,8 @@ The NSE table was created for:
 
 
 
+.. _self_consistent_nse:
+
 Self-consistent NSE
 ===================
 

sphinx_docs/source/rp_intro.rst

@@ -23,7 +23,10 @@ the parameter with the highest priority takes precedence. This allows
 specific implementations to override the general parameter defaults.
 
 The documentation below is automatically generated, using the comments
-in the ``_parameters`` files.
+in the ``_parameters`` files.  The parameters are grouped by the
+namespace under which they live, and parameters that only apply to
+specific build configurations or have their defaults overridden are
+noted in separate tables.
 
 
 .. toctree::