rda-python-miscs 2.0.4__tar.gz → 2.0.6__tar.gz

{rda_python_miscs-2.0.4 → rda_python_miscs-2.0.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.4
+Version: 2.0.6
 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.4 → rda_python_miscs-2.0.6}/pyproject.toml

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

{rda_python_miscs-2.0.4 → rda_python_miscs-2.0.6}/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']
 
    #
@@ -129,7 +126,7 @@ class PgRST(PgFile, PgUtil):
 
       This is the main entry point.  It populates ``self.sections``,
       ``self.options``, and ``self.examples`` by calling ``parse_docs``, then
-      writes ``index.rst``, ``toc.rst``, and one ``section<id>.rst`` per
+      writes ``index.rst`` and one ``section<id>.rst`` per
       section into ``DOCDIR``.
 
       Args:
@@ -150,13 +147,11 @@ class PgRST(PgFile, PgUtil):
       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
+      if op.exists(op.join(self.DOCS['DOCDIR'], "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_toc()
-
       for section in self.sections:
          self.write_section(section)
 
@@ -166,12 +161,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``.
@@ -192,14 +183,6 @@ 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)
             if ms:   # start new section
                section = self.record_section(section, option, example, ms.group(1), ms.group(2))
@@ -300,10 +283,16 @@ 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'])
+         lines = example['desc'].split('\n')
+         first_line = lines[0]
+         rest = '\n'.join(lines[1:]) if len(lines) > 1 else ''
+         ms = re.match(r'^(.*)\.\s*(.*)$', first_line)
          if ms:
             example['title'] = ms.group(1)
-            example['desc'] = ms.group(2)
+            example['desc'] = (ms.group(2) + '\n' + rest) if rest else ms.group(2)
+         else:
+            example['title'] = first_line
+            example['desc'] = rest
          option['exmidxs'].append(len(self.examples))   # record example index in option
          self.examples.append(example)     # record example globally
 
@@ -396,7 +385,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
@@ -404,29 +394,17 @@ class PgRST(PgFile, PgUtil):
    def write_index(self, section):
       """Write ``index.rst`` from the ``index.rst.temp`` template.
 
-      Passes ``TITLE`` (document title) and ``SECID`` (first section id)
-      as substitution variables.
+      Passes ``TITLE`` (document title), ``SECID`` (first section id),
+      and the generated ``TOC`` RST content as substitution variables.
 
       Args:
          section (dict): The first section dict, used to supply ``SECID``.
       """
-      hash = {'TITLE' : self.DOCS['DOCTIT'], 'SECID' : section['secid']}
+      hash = {'TITLE' : self.DOCS['DOCTIT'], 'SECID' : section['secid'],
+              'TOC'   : self.create_toc()}
 
       self.template_to_rst("index", hash)
 
-   #
-   # write the table of contents: toc.rst
-   #
-   def write_toc(self):
-      """Write ``toc.rst`` from the ``toc.rst.temp`` template.
-
-      Passes ``TITLE`` and the generated ``TOC`` RST content as substitution
-      variables.
-      """
-      hash = {'TITLE' : self.DOCS['DOCTIT'], 'TOC' : self.create_toc()}
-
-      self.template_to_rst("toc", hash)
-
    #
    # write a section rst file
    #
@@ -495,8 +473,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.
@@ -504,29 +482,38 @@ 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
 
       # 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"
-
-      # appendix A: list of examples
-      content += "**Appendix A: List of Examples**\n\n"
-
+         level = section['level']
+         if csecid:
+            if not secid.startswith(csecid + "."): continue
+         elif level > (clevel+1):
+            continue
+         content += "   section{}\n".format(secid)
+
+      if not content: return ""
+
+      content = f".. toctree::\n   :maxdepth: {depth}\n   :caption: Table of Contents\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(csecid + "."):
+            appendix += "- `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
 
@@ -551,6 +538,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
 
    #
@@ -626,7 +614,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:
@@ -638,7 +626,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)
 
@@ -651,8 +639,9 @@ class PgRST(PgFile, PgUtil):
       """Scan *line* for option references, section-category keywords, URLs, and
       quoted program names, and replace each with an RST hyperlink.
 
-      Link targets are formatted as RST anonymous hyperlinks:
-      `` `text <url>`_ ``.
+      All links use RST named anchor references (`` `name`_ `` or
+      `` `text <name_>`_ ``) targeting anchors of the form ``.. _name:``.
+      Cross-file option links target ``.. _section{secid}:`` anchors.
 
       Args:
          line   (str): Source text line to process.
@@ -687,14 +676,15 @@ class PgRST(PgFile, PgUtil):
          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:
-            link = "#{}".format(opt)
+            anchor = opt
          elif self.options[opt]['type'] == "Action":
-            link = "section{}.rst".format(secid)
+            anchor = "section{}".format(secid)
          elif ptype == 2 and opt == "FN":
-            link = "#field"
+            anchor = "field"
          else:
-            link = "section{}.rst#{}".format(secid, opt)
+            anchor = "section{}".format(secid)
 
          ms = re.search(r'-\(({}\|\w+)\)'.format(opt), line)
          if ms:
@@ -703,7 +693,10 @@ class PgRST(PgFile, PgUtil):
             after = ')'
 
          replace = pre + opt + after
-         link = "{}`{} <{}>`_{}".format(pre, opt, link, after)
+         if opt == anchor:
+            link = "{}`{}`_{}".format(pre, opt, after)
+         else:
+            link = "{}`{} <{}_>`_{}".format(pre, opt, anchor, after)
          line = line.replace(replace, link)
 
       opts = re.findall(r'(^|\W){}( Options*\W|\W|$)'.format(self.SEARCH), line)
@@ -720,9 +713,9 @@ class PgRST(PgFile, PgUtil):
             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 = "{}`{} <mode_>`_{}".format(pre, opt, after)
          else:
-            link = "{}`{} <section{}.rst>`_{}".format(pre, opt, secid, after)
+            link = "{}`{} <section{}>`_{}".format(pre, opt, secid, after)
          line = line.replace(replace, link)
 
       ms = re.search(r'(https*://\S+)(\.|\,)', line)
@@ -743,10 +736,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
 
    #
@@ -888,7 +877,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.
@@ -909,7 +897,7 @@ class PgRST(PgFile, PgUtil):
             line = lines[i]
             ms = re.match(r'^\s+-\s+(.*)', line)
             if ms:
-               content += "#. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"
+               content += "* " + self.replace_option_link(ms.group(1), secid, 1) + "\n"
             else:
                content += "   " + self.replace_option_link(line, secid, 1) + "\n"
          content += "\n"
@@ -1040,7 +1028,7 @@ class PgRST(PgFile, PgUtil):
             if ms:
                content += "| {}{}{} {}\n".format(self.Q1, self.DOCS['DOCNAM'], self.Q2, ms.group(1))
             else:
-               content += "|   {}\n".format(line.strip())
+               content += "|{}\n".format(line)
       content += "\n"
 
       return content
@@ -1086,11 +1074,11 @@ 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.
       """
       for section in self.sections:
          if title == section['title']:
-            return "`{} <section{}.rst>`_".format(title, section['secid'])
+            return "`{} <section{}>`_".format(title, section['secid'])
 
       return title
 

{rda_python_miscs-2.0.4 → rda_python_miscs-2.0.6}/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,15 +14,4 @@
 A GUIDE TO __TITLE__
 ============================
 
-.. contents:: Table of Contents
-   :depth: 2
-   :local:
-
-See the :doc:`toc` for the full table of contents.
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents
-
-   toc
-   section__SECID__
+__TOC__

{rda_python_miscs-2.0.4 → rda_python_miscs-2.0.6}/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,8 +15,5 @@ __SECID__ - __TITLE__
 
 __SECTION__
 
-.. raw:: html
-
-   <br>
 
 :ref:`Back to Top <index>`

{rda_python_miscs-2.0.4 → rda_python_miscs-2.0.6}/src/rda_python_miscs.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.4
+Version: 2.0.6
 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