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

rda_python_miscs-2.0.5/MANIFEST.in

@@ -0,0 +1,2 @@
+include src/rda_python_miscs/*.usg
+include src/rda_python_miscs/rst_templates/*.temp

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

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

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

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

@@ -129,7 +129,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:
@@ -155,8 +155,6 @@ class PgRST(PgFile, PgUtil):
       else:
          self.write_index(self.sections[0])
 
-      self.write_toc()
-
       for section in self.sections:
          self.write_section(section)
 
@@ -404,29 +402,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
    #
@@ -651,8 +637,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 +674,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 +691,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 +711,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)
@@ -1119,9 +1110,10 @@ class PgRST(PgFile, PgUtil):
 
       Resolution order for OPTS / ALIAS:
 
-      1. Module-level ``OPTS`` / ``ALIAS`` attributes.
-      2. The first class *defined in that module* that carries both ``OPTS``
-         and ``ALIAS`` as class-level attributes.
+      1. The first class *defined in that module* that carries ``OPTS``
+         as a class-level attribute.
+      2. Module-level ``OPTS`` / ``ALIAS`` attributes (fallback when no
+         qualifying class is found).
 
       ``ALIAS`` is optional; an empty dict is returned when not found.
 
@@ -1155,25 +1147,26 @@ class PgRST(PgFile, PgUtil):
       # Derive ORIGIN from the module's own file path.
       origin = op.dirname(op.abspath(mod.__file__))
 
-      # 1. Try module-level attributes first.
-      opts  = getattr(mod, 'OPTS',  None)
-      alias = getattr(mod, 'ALIAS', None)
-
-      # 2. Fall back to the first class in the module that owns both.
-      if opts is None or alias is None:
-         for _, obj in inspect.getmembers(mod, inspect.isclass):
-            if obj.__module__ == modname:
-               cls_opts  = getattr(obj, 'OPTS',  None)
-               cls_alias = getattr(obj, 'ALIAS', None)
-               if cls_opts is not None:
-                  if opts  is None: opts  = cls_opts
-                  if alias is None: alias = cls_alias
-                  break
+      # 1. Find the first class defined in this module and read OPTS / ALIAS from it.
+      cls = next(
+         (obj for _, obj in inspect.getmembers(mod, inspect.isclass)
+          if obj.__module__ == modname),
+         None,
+      )
+
+      if cls is not None:
+         obj   = cls()
+         opts  = getattr(obj, 'OPTS',  None)
+         alias = getattr(obj, 'ALIAS', None)
+      else:
+         # 2. Fall back to module-level attributes when no class is found.
+         opts  = getattr(mod, 'OPTS',  None)
+         alias = getattr(mod, 'ALIAS', None)
 
       if opts is None:
          self.pglog(
-            "Module '{}' does not define OPTS (checked module level and "
-            "all classes defined in the module)".format(modname),
+            "Module '{}' does not define OPTS (checked class and "
+            "module level)".format(modname),
             self.LGWNEX,
          )
 

rda_python_miscs-2.0.5/src/rda_python_miscs/rst_templates/index.rst.temp

@@ -0,0 +1,24 @@
+################################################################################
+#
+#     Title : index.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
+#
+################################################################################
+
+.. _index:
+
+============================
+A GUIDE TO __TITLE__
+============================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents
+
+   section__SECID__
+
+__TOC__

rda_python_miscs-2.0.5/src/rda_python_miscs/rst_templates/section.rst.temp

@@ -0,0 +1,20 @@
+################################################################################
+#
+#     Title : section.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
+#
+################################################################################
+
+.. _section__SECID__:
+
+__SECID__ - __TITLE__
+=====================
+
+__SECTION__
+
+
+:ref:`Back to Top <index>`

rda_python_miscs-2.0.5/src/rda_python_miscs/rst_templates/toc.rst.temp

@@ -0,0 +1,21 @@
+################################################################################
+#
+#     Title : toc.temp
+#    Author : Zaihua Ji,  zji@ucar.edu
+#      Date : 03/17/2026
+#   Purpose : template file for help document toc.rst (table of contents, RST)
+#
+# Work File : $DSSHOME/lib/templates/toc.temp
+#
+################################################################################
+
+.. _toc:
+
+====================
+__TITLE__ Guide
+====================
+
+Table of Contents
+-----------------
+
+__TOC__

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rda_python_miscs
-Version: 2.0.3
+Version: 2.0.5
 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.3 → rda_python_miscs-2.0.5}/src/rda_python_miscs.egg-info/SOURCES.txt

@@ -46,4 +46,7 @@ src/rda_python_miscs.egg-info/dependency_links.txt
 src/rda_python_miscs.egg-info/entry_points.txt
 src/rda_python_miscs.egg-info/requires.txt
 src/rda_python_miscs.egg-info/top_level.txt
+src/rda_python_miscs/rst_templates/index.rst.temp
+src/rda_python_miscs/rst_templates/section.rst.temp
+src/rda_python_miscs/rst_templates/toc.rst.temp
 tests/test_miscs.py

rda_python_miscs-2.0.3/MANIFEST.in

@@ -1 +0,0 @@
-include src/rda_python_miscs/*.usg