rda-python-miscs 2.0.5__tar.gz → 2.0.7__tar.gz

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.5
+Version: 2.0.7
 Summary: RDA Python package to hold RDA miscellaneous utility programs
 Author-email: Zaihua Ji <zji@ucar.edu>
 Project-URL: Homepage, https://github.com/NCAR/rda-python-miscs

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rda_python_miscs"
-version = "2.0.5"
+version = "2.0.7"
 authors = [
   { name="Zaihua Ji", email="zji@ucar.edu" },
 ]

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/src/rda_python_miscs/pg_rst.py

@@ -22,7 +22,6 @@ from os import path as op
 from rda_python_common.pg_file import PgFile
 from rda_python_common.pg_util import PgUtil
 
-
 class PgRST(PgFile, PgUtil):
    """Convert text-based program usage documents (.usg files) into
    reStructuredText (.rst) files using RST template files.
@@ -48,7 +47,7 @@ class PgRST(PgFile, PgUtil):
    Q0 = "'"
    Q1 = "**"       # RST bold open  (was "<i><b>")
    Q2 = "**"       # RST bold close (was "</i></b>")
-
+   TLEVEL = 3       # max section level to be rendered (1, 2, or 3)
    EMLIST = {
       'dsarch' : 1,
       'msarch' : 1,
@@ -60,7 +59,6 @@ class PgRST(PgFile, PgUtil):
       'rcm' : 1,
       'dcm' : 1,
    }
-
    SEARCH = "(Action|Info|Mode|Multi-Value|Single-Value)"
 
    def __init__(self):
@@ -116,7 +114,6 @@ class PgRST(PgFile, PgUtil):
          'DOCTIT' : "", # document name in upper case letters
          'DOCLNK' : None,
       }
-
       self.LINKS = ['dsarch', 'dsupdt', 'dsrqst', 'dscheck']
 
    #
@@ -142,19 +139,13 @@ class PgRST(PgFile, PgUtil):
 
       self.parse_docs(docname)
       if not self.sections: self.pglog(docname + ": empty document", self.LGWNEX)
-
       self.DOCS['DOCNAM'] = docname
       if docname in self.LINKS: self.LINKS.remove(docname)
       self.DOCS['DOCLNK'] = r"({})".format('|'.join(self.LINKS))
       self.DOCS['DOCTIT'] = docname.upper()
       self.change_local_directory(self.DOCS['DOCDIR'], self.LGWNEX)
       self.pglog("Write rst document '{}' under {}".format(docname, self.DOCS['DOCDIR']), self.LOGWRN)
-
-      if op.exists("index.rst"):  # write index file once
-         self.pglog("index.rst exists already, delete first if needs to be regenerated", self.LOGWRN)
-      else:
-         self.write_index(self.sections[0])
-
+      self.write_index(self.sections[0])
       for section in self.sections:
          self.write_section(section)
 
@@ -164,12 +155,8 @@ class PgRST(PgFile, PgUtil):
    def parse_docs(self, docname):
       """Read *docname*.usg and populate ``sections``, ``options``, and ``examples``.
 
-      Lines beginning with ``#`` are treated as comments and skipped.  Inline
-      trailing comments are also stripped.  Angle-bracketed uppercase tokens
-      (e.g. ``<FILENAME>``) are temporarily escaped to ``&ltFILENAME&gt``
-      so they are not misidentified as option markers (``<:>``, ``<=>``,
-      ``<!>``) later in processing.  They are unescaped back to ``<FILENAME>``
-      in :meth:`replace_option_link` before appearing in RST output.
+      Lines beginning with ``#`` are treated as comments and skipped.  In-line
+      trailing comments are also stripped.
 
       Args:
          docname (str): Short document name used to locate ``<ORIGIN>/<docname>.usg``.
@@ -190,15 +177,7 @@ class PgRST(PgFile, PgUtil):
             else:
                line = line.rstrip()   # remove trailing white spaces
 
-            # Temporarily escape <UPPERCASE> tokens so they are not confused
-            # with special markers like <:>, <=>, <!> used in option parsing.
-            while True:
-               ms = re.search(r'(<([A-Z/\-\.]+)>)', line)
-               if ms:
-                  line = line.replace(ms.group(1), "&lt{}&gt".format(ms.group(2)))
-               else:
-                  break
-            ms = re.match(r'^([\d\.]+)\s+(.+)$', line)
+            ms = re.match(r'^([\d\.]+)\s+([A-Z].+)$', line)
             if ms:   # start new section
                section = self.record_section(section, option, example, ms.group(1), ms.group(2))
                option = example = None
@@ -298,10 +277,18 @@ class PgRST(PgFile, PgUtil):
          dict | None: A new example dict when *ndesc* is given, else ``None``.
       """
       if example:
-         ms = re.match(r'^(.*)\.\s*(.*)$', example['desc'])
-         if ms:
-            example['title'] = ms.group(1)
-            example['desc'] = ms.group(2)
+         lines = example['desc'].split('\n')
+         lcnt = len(lines)
+         title = lines[0].strip()
+         ol = 1
+         if title[-1] != ':':
+            for l in range(1, lcnt):
+               line = lines[l].strip()
+               title += ' ' + line
+               ol += 1
+               if line[-1] == ':': break
+         example['desc'] = '\n'.join(lines[ol:]) if lcnt > ol else ''
+         example['title'] = title
          option['exmidxs'].append(len(self.examples))   # record example index in option
          self.examples.append(example)     # record example globally
 
@@ -394,7 +381,8 @@ class PgRST(PgFile, PgUtil):
       Returns:
          dict: New example dict with keys ``opt``, ``title``, and ``desc``.
       """
-      return {'opt' : opt, 'title' : "", 'desc' : desc.title() + "\n"}
+      desc = (desc[0].upper() + desc[1:]) if desc else desc
+      return {'opt' : opt, 'title' : "", 'desc' : desc + "\n"}
 
    #
    # write the entry file: index.rst
@@ -481,8 +469,8 @@ class PgRST(PgFile, PgUtil):
    #
    # create rst content for table of contents
    #
-   def create_toc(self):
-      """Build and return the RST table-of-contents string.
+   def create_toc(self, csection=None):
+      """Build and return the RST table-of-contents string of a given section.
 
       Produces a nested bullet list of section links (indented by section
       level) followed by a flat Appendix A list of all example links.
@@ -490,29 +478,36 @@ class PgRST(PgFile, PgUtil):
       Returns:
          str: RST-formatted TOC content ready for ``__TOC__`` substitution.
       """
+      
       content = ""
+      clevel = csection['level'] if csection else 0
+      csecid = csection['secid'] if csection else ""
+      depth = self.TLEVEL - clevel
+      level = clevel+1
+      preid = csecid+'.'
 
       # nested bullet list for all sections
       for section in self.sections:
          secid = section['secid']
-         indent = "   " * (section['level'] - 1)
-         content += "{}- `{}. {} <section{}.rst>`_\n".format(
-            indent, secid, section['title'], secid)
-
-      content += "\n"
+         if csecid and not secid.startswith(preid): continue
+         if section['level'] == level: content += "   section{}\n".format(secid)
 
-      # appendix A: list of examples
-      content += "**Appendix A: List of Examples**\n\n"
+      if not content: return ""
 
+      content = f".. toctree::\n   :maxdepth: {depth}\n   :caption: Table of Contents\n\n{content}\n"
+      # appendix A: list of examples for the parent section and its subsections
+      appendix = ""
       idx = 1  # used as example index
-      for example in self.examples:
-         opt = example['opt']
+      for exm in self.examples:
+         opt = exm['opt']
          option = self.options[opt]
          secid = option['secid']
-         content += "- `A.{}. {} Option -{} (-{}) <section{}.rst#e{}>`_\n".format(
-            idx, option['type'], opt, option['name'], secid, idx)
+         if not csecid or secid == csecid or secid.startswith(preid):
+            appendix += "- :ref:`A.{}. {} Option -{} (-{}) <{}_e{}>`\n".format(
+                        idx, option['type'], opt, option['name'], secid, idx)
          idx += 1
-      content += "\n"
+      if appendix:
+         content += "**Appendix A: List of Examples**\n\n" + appendix + "\n"
 
       return content
 
@@ -537,6 +532,7 @@ class PgRST(PgFile, PgUtil):
       for opt in section['opts']:
          content += self.create_option(opt, secid)
 
+      content += self.create_toc(section)  # add a local TOC for the section and its subsections
       return content
 
    #
@@ -575,7 +571,7 @@ class PgRST(PgFile, PgUtil):
       Emits a ``.. _<opt>:`` label followed by a title line of the form::
 
          <Type> Option -**XX** (-**longname**) [Alias(es): ...] :
-         ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
       The ``~`` underline is sized to match the actual title line length
       (including RST bold markers).
@@ -602,7 +598,7 @@ class PgRST(PgFile, PgUtil):
 
       content = "\n.. _{}:\n\n".format(opt)
       content += title + "\n"
-      content += "~" * len(title) + "\n\n"
+      content += "^" * len(title) + "\n\n"
 
       return content
 
@@ -612,7 +608,7 @@ class PgRST(PgFile, PgUtil):
    def create_example(self, exmidx, secid):
       """Build the RST content for a single example.
 
-      Emits a ``.. _e<N>:`` anchor, a bold ``EXAMPLE N. <title>`` heading,
+      Emits a ``.. _secid_e<N>:`` anchor, a bold ``EXAMPLE N. <title>`` heading,
       and the example's body description.
 
       Args:
@@ -624,7 +620,7 @@ class PgRST(PgFile, PgUtil):
       """
       example = self.examples[exmidx]
       exm = exmidx + 1
-      content = "\n.. _e{}:\n\n".format(exm)
+      content = "\n.. _{}_e{}:\n\n".format(secid, exm)
       content += "**EXAMPLE {}. {}**\n\n".format(exm, example['title'])
       content += self.create_description(example['desc'], secid, 2)
 
@@ -671,33 +667,27 @@ class PgRST(PgFile, PgUtil):
 
       for optary in opts:
          opt = self.get_short_option(optary[1])
+      
          pre = optary[0]
          after = optary[2]
          secid = self.options[opt]['secid']
-         anchor = None   # RST anchor name for same-file or cross-file links (.. _NAME:)
-         if secid == csecid:
-            anchor = opt
-         elif self.options[opt]['type'] == "Action":
-            anchor = "section{}".format(secid)
-         elif ptype == 2 and opt == "FN":
-            anchor = "field"
-         else:
-            anchor = "section{}".format(secid)
-
-         ms = re.search(r'-\(({}\|\w+)\)'.format(opt), line)
+         anchor = opt
+         ms = re.search(r'(-\({}\|\w+\))'.format(opt), line)
          if ms:
             if secid == csecid and ptype == 2: continue
             opt = ms.group(1)
-            after = ')'
+            pre = after = ''
+         else:
+            ms = re.search(r'(-{})'.format(opt), line)
+            if ms:
+               opt = ms.group(1)
+               pre = pre[:-1]
 
          replace = pre + opt + after
-         if opt == anchor:
-            link = "{}`{}`_{}".format(pre, opt, after)
-         else:
-            link = "{}`{} <{}_>`_{}".format(pre, opt, anchor, after)
+         link = "{}:ref:`{} <{}>`{}".format(pre, opt, anchor, after)
          line = line.replace(replace, link)
 
-      opts = re.findall(r'(^|\W){}( Options*\W|\W|$)'.format(self.SEARCH), line)
+      opts = re.findall(r'(^|\W){}(\s+(o|O)ptions*\W|\W|$)'.format(self.SEARCH), line)
       for optary in opts:
          opt = optary[1]
          if not self.SECIDS[opt]: continue
@@ -706,20 +696,14 @@ class PgRST(PgFile, PgUtil):
          pre = optary[0]
          after = optary[2]
          replace = pre + opt + after
-         ms = re.search(r'(\sOptions*)\W', after)
+         ms = re.search(r'(\s+Options*)\W', after, re.I)
          if ms:
             opt += ms.group(1)
             after = after.replace(ms.group(1), '')
          if ptype == 2 and re.search(r'Mode Options*', opt) and dtype == 3:
-            link = "{}`{} <mode_>`_{}".format(pre, opt, after)
+            link = "{}:ref:`{} <mode{}>`{}".format(pre, opt, csecid, after)
          else:
-            link = "{}`{} <section{}_>`_{}".format(pre, opt, secid, after)
-         line = line.replace(replace, link)
-
-      ms = re.search(r'(https*://\S+)(\.|\,)', line)
-      if ms:
-         replace = ms.group(1)
-         link = "`{} <{}>`_".format(replace, replace)
+            link = "{}:ref:`{} <section{}>`{}".format(pre, opt, secid, after)
          line = line.replace(replace, link)
 
       # Q0...Q0 is a source-document quoting convention: Q0wordQ0 marks
@@ -734,10 +718,6 @@ class PgRST(PgFile, PgUtil):
             link = self.Q1 + opt + self.Q2
          line = line.replace(replace, link)
 
-      # Unescape <UPPERCASE> tokens that were temporarily escaped during
-      # parsing to avoid confusion with option markers (<:>, <=>, <!>).
-      line = line.replace('&lt', '<').replace('&gt', '>')
-
       return line
 
    #
@@ -778,7 +758,7 @@ class PgRST(PgFile, PgUtil):
                   lines = []
                   ptype = 1
                   cnt = 0
-               elif cnt == 1 and re.match(r'^\s+%s\s(-|\[|ds\d*|\d+|[A-Z]{2}\s)' % self.DOCS['DOCNAM'], line):
+               elif cnt == 1 and re.match(r'^\s+%s\s(-|\[|[a-z]\d{6}|[A-Z]{2}\s)' % self.DOCS['DOCNAM'], line):
                   ptype = 2
          elif cnt > 0:
             content += self.create_desc_content(lines, cnt, secid, dtype, ptype)
@@ -823,7 +803,7 @@ class PgRST(PgFile, PgUtil):
 
       * ``dtype=2`` with a ``<<Content ...>>`` header line: renders the
         remaining lines as a verbatim content block.
-      * ``dtype=3``: prefixes "Mode options that…" lines with a ``.. _mode:``
+      * ``dtype=3``: prefixes "Mode options that…" lines with a ``.. _mode<secid>:``
         anchor and "Use Info option -FN…" lines with a ``.. _field:`` anchor.
 
       Args:
@@ -843,30 +823,27 @@ class PgRST(PgFile, PgUtil):
       if dtype == 2:
          ms = re.match(r'^<<(Content .*)>>$', line0)
          if ms:   # input files for examples
-            content += ms.group(1) + ":\n\n"
+            content += ms.group(1) + ":\n\n.. code-block:: none\n\n"
             normal = 0
             for i in range(1, cnt):
                line = lines[i]
                if doreplace and line.find('<:>') > -1 and not re.match(r'^[A-Z]\w+<:>[A-Z]\w+<:>', line):
                   doreplace = 0
                if doreplace:
-                  content += self.replace_option_link(line, secid, 0) + "\n"
+                  content += ' '+self.replace_option_link(line, secid, 0) + "\n"
                else:
-                  content += line + "\n"
+                  content += ' '+line + "\n"
                   if re.match(r'^\[\w+\]$', line): doreplace = 1
             content += "\n"
       if normal:   # normal paragraph
          ii = 0
          if dtype == 3:
             if re.match(r'^\s*Mode options* that ', line0):
-               content += ".. _mode:\n\n" + self.replace_option_link(line0, secid, 0) + "\n"
-               ii = 1
-            elif re.match(r'^\s*Use Info option -FN ', line0):
-               content += ".. _field:\n\n" + self.replace_option_link(line0, secid, 0) + "\n"
+               content += f".. _mode{secid}:\n\n" + self.replace_option_link(line0, secid, 0).strip() + "\n"
                ii = 1
          for i in range(ii, cnt):
             line = lines[i]
-            content += self.replace_option_link(line, secid, 0) + "\n"
+            content += self.replace_option_link(line, secid, 0).strip() + "\n"
          content += "\n"
 
       return content
@@ -879,7 +856,6 @@ class PgRST(PgFile, PgUtil):
 
       Detects three sub-formats:
 
-      * Lines starting with ``- `` → RST numbered list (``#.``).
       * Lines ending with ``=>`` → RST line block (``|``).
       * Lines split on `` - `` (key-value pairs) → ``.. list-table::`` directive.
       * All other lines split on 2+ spaces → RST simple table.
@@ -894,16 +870,17 @@ class PgRST(PgFile, PgUtil):
       """
       line0 = lines[0]
       ms = re.match(r'^\s+-\s+(.*)', line0)
-      if ms:   # create a numbered list
-         content = "#. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"
+      if ms:
+         content = "* " + self.replace_option_link(ms.group(1), secid, 1)
          for i in range(1, cnt):
             line = lines[i]
             ms = re.match(r'^\s+-\s+(.*)', line)
             if ms:
-               content += "#. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"
+               content += "\n* " + self.replace_option_link(ms.group(1), secid, 1)
             else:
-               content += "   " + self.replace_option_link(line, secid, 1) + "\n"
-         content += "\n"
+               
+               content += " " + self.replace_option_link(line, secid, 1).lstrip()
+         content += "\n\n"
       elif re.search(r'=>$', line0):
          line = re.sub(r'={1,}', '=', line0)
          content = "| {}\n".format(line)
@@ -937,22 +914,22 @@ class PgRST(PgFile, PgUtil):
                   prev_vals[1] += " " + self.replace_option_link(line, secid, 1)
             if prev_vals:
                rows.append(tuple(prev_vals))
-            content = self._build_rst_list_table(rows)
+            content = self.build_rst_list_table(rows)
          else:
             # multi-column table split on 2+ spaces
             rows = []
             for i in range(cnt):
-               line = lines[i]
+               line = lines[i].strip()
                vals = re.split(r'\s{2,}', self.replace_option_link(line, secid, 1))
                rows.append(vals)
-            content = self._build_rst_simple_table(rows) + "\n"
+            content = self.build_rst_simple_table(rows) + "\n"
 
       return content
 
    #
    # build a two-column rst list-table
    #
-   def _build_rst_list_table(self, rows):
+   def build_rst_list_table(self, rows):
       """Render *rows* as an RST ``.. list-table::`` directive.
 
       Args:
@@ -962,9 +939,11 @@ class PgRST(PgFile, PgUtil):
          str: RST list-table directive string, or ``''`` if *rows* is empty.
       """
       if not rows: return ""
-      content = ".. list-table::\n   :widths: auto\n\n"
+      content = ".. list-table::\n   :widths: auto\n   :header-rows: 0\n\n"
       for col0, col1 in rows:
+         if col0[0] == '-': col0 = col0[1:]
          content += "   * - {}\n".format(col0)
+         if col1[0] == '-': col1 = col1[1:]
          content += "     - {}\n".format(col1)
       content += "\n"
       return content
@@ -972,7 +951,7 @@ class PgRST(PgFile, PgUtil):
    #
    # build a multi-column rst simple table
    #
-   def _build_rst_simple_table(self, rows):
+   def build_rst_simple_table(self, rows):
       """Render *rows* as an RST simple (grid-free) table.
 
       Column widths are computed from the widest cell in each column, with a
@@ -993,11 +972,17 @@ class PgRST(PgFile, PgUtil):
             if j < ncols:
                widths[j] = max(widths[j], len(val), 1)
       sep = "  ".join("=" * w for w in widths) + "\n"
-      content = sep
+#      content = sep
+      content = ".. list-table::\n   :widths: auto\n   :header-rows: 1\n\n"
       for row in rows:
-         padded = ["{:<{}}".format(row[j] if j < len(row) else "", widths[j]) for j in range(ncols)]
-         content += "  ".join(padded) + "\n"
-      content += sep
+         v = row[0] + "\n"
+         if len(v) > 1 and v[0] == '-': v = v[1:]
+         content += "   * - " + v
+         for c in range(1, ncols):
+            v = row[c] + "\n"
+            if len(v) > 1 and v[0] == '-': v = v[1:]
+            content += "     - " + v
+
       return content
 
    #
@@ -1024,14 +1009,11 @@ class PgRST(PgFile, PgUtil):
 
       for i in range(cnt):
          line = self.replace_option_link(lines[i], secid, 2, dtype)
-         if re.search(r'\sor\s', line, re.I):
-            content += "\n**Or**\n\n"
+         ms = re.match(r'^\s*{}\s+(.+)$'.format(self.DOCS['DOCNAM']), line)
+         if ms:
+            content += "|  {}{}{} {}\n".format(self.Q1, self.DOCS['DOCNAM'], self.Q2, ms.group(1))
          else:
-            ms = re.match(r'^\s*{}\s+(.+)$'.format(self.DOCS['DOCNAM']), line)
-            if ms:
-               content += "| {}{}{} {}\n".format(self.Q1, self.DOCS['DOCNAM'], self.Q2, ms.group(1))
-            else:
-               content += "|   {}\n".format(line.strip())
+            content += "|    "+line+"\n"
       content += "\n"
 
       return content
@@ -1077,11 +1059,13 @@ class PgRST(PgFile, PgUtil):
          title (str): Section title text to look up.
 
       Returns:
-         str: RST `` `title <sectionN.rst>`_ `` link, or *title* if not found.
+         str: RST `` `title <sectionN>`_ `` link, or *title* if not found.
       """
+      ltitle = title.lower()
+      if ltitle == "info options": ltitle = 'information options'
       for section in self.sections:
-         if title == section['title']:
-            return "`{} <section{}.rst>`_".format(title, section['secid'])
+         if ltitle == section['title'].lower():
+            return ":ref:`{} <section{}>`".format(title, section['secid'])
 
       return title
 

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/src/rda_python_miscs/rst_templates/index.rst.temp

@@ -1,11 +1,10 @@
 ################################################################################
 #
-#     Title : index.temp
+#     Title : index_rst.temp
 #    Author : Zaihua Ji,  zji@ucar.edu
 #      Date : 03/17/2026
 #   Purpose : template file for help document index.rst (reStructuredText)
-#
-# Work File : $DSSHOME/lib/templates/index.temp
+#    Github : https://github.com/NCAR/rda-python-mics.git
 #
 ################################################################################
 
@@ -15,10 +14,6 @@
 A GUIDE TO __TITLE__
 ============================
 
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
-
-   section__SECID__
+__TOC__
 
-__TOC__
+:ref:`Back to Top <index>`

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/src/rda_python_miscs/rst_templates/section.rst.temp

@@ -1,11 +1,10 @@
 ################################################################################
 #
-#     Title : section.temp
+#     Title : section_rst.temp
 #    Author : Zaihua Ji,  zji@ucar.edu
 #      Date : 03/17/2026
 #   Purpose : template file for help document section.rst (reStructuredText)
-#
-# Work File : $DSSHOME/lib/templates/section.temp
+#    Github : https://github.com/NCAR/rda-python-mics.git
 #
 ################################################################################
 
@@ -16,5 +15,5 @@ __SECID__ - __TITLE__
 
 __SECTION__
 
-
-:ref:`Back to Top <index>`
+:ref:`Back to Top <section__SECID__>`
+:ref:`Back to Table of Contents <index>`

{rda_python_miscs-2.0.5 → rda_python_miscs-2.0.7}/src/rda_python_miscs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.5
+Version: 2.0.7
 Summary: RDA Python package to hold RDA miscellaneous utility programs
 Author-email: Zaihua Ji <zji@ucar.edu>
 Project-URL: Homepage, https://github.com/NCAR/rda-python-miscs