overhaul pg_rst.py to dump proper *.rst files by zaihuaji · Pull Request #17 · NCAR/rda-python-miscs

zaihuaji · 2026-03-26T21:28:21Z

No description provided.

Copilot

Pull request overview

This PR updates the RST generation pipeline in pg_rst.py and its templates to produce more “Sphinx-friendly” .rst output (notably by moving TOC construction into generated content and updating link/anchor behavior), and bumps the package version.

Changes:

Updates index.rst.temp to rely on a generated __TOC__ block instead of a static .. toctree:: template.
Refactors PgRST.create_toc() to emit a .. toctree:: directive and attempts to add per-section/local TOCs.
Adjusts internal link formats/anchors (sections/examples) and bumps project version to 2.0.6.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 9 comments.

File	Description
`src/rda_python_miscs/rst_templates/section.rst.temp`	Updates template header metadata for generated section pages.
`src/rda_python_miscs/rst_templates/index.rst.temp`	Simplifies index template and delegates TOC rendering to generated `__TOC__`.
`src/rda_python_miscs/pg_rst.py`	Core logic changes for TOC generation, linking, list rendering, and section rendering flow.
`pyproject.toml`	Version bump to `2.0.6`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-26T21:33:37Z

            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"


In create_table(), numbered list items should use #. (or explicit numbers) for each list item. *. is not valid reStructuredText list syntax and will render incorrectly.

Suggested change

content += "*. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"

content += "#. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"

Copilot · 2026-03-26T21:33:37Z

+#     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


The header comment’s GitHub URL appears to have a typo ("rda-python-mics" vs this repo/package name "rda_python_miscs" / "rda-python-miscs"). Also the "Title" comment says index_rst.temp but the actual filename is index.rst.temp. Please update these header metadata lines to match the real file/repo.

Copilot · 2026-03-26T21:33:37Z

      for opt in section['opts']:
         content += self.create_option(opt, secid)

+      content += create_toc(section)  # add a local TOC for the section and its subsections


create_section() calls create_toc(section) without self., which will raise NameError (and also bypasses the class method). Call self.create_toc(section) instead.

Suggested change

content += create_toc(section) # add a local TOC for the section and its subsections

content += self.create_toc(section) # add a local TOC for the section and its subsections

Copilot · 2026-03-26T21:33:38Z

            link = "{}`{} <mode_>`_{}".format(pre, opt, after)
         else:
-            link = "{}`{} <section{}_>`_{}".format(pre, opt, secid, after)
+            link = "{}`{} <section{}>`_{}".format(pre, opt, secid, after)


This link target uses <section{}> whereas other internal references in this module use the named-target form <..._> (see the option-link branch just above). As written, this will be treated as a URI-like relative link rather than a reference to the .. _section<id>: target. Please make the target consistent (or switch to Sphinx :ref:/:doc: roles).

Suggested change

link = "{}`{} <section{}>`_{}".format(pre, opt, secid, after)

link = "{}`{} <section{}_>`_{}".format(pre, opt, secid, after)

Copilot · 2026-03-26T21:33:38Z

      for section in self.sections:
         if title == section['title']:
-            return "`{} <section{}.rst>`_".format(title, section['secid'])
+            return "`{} <section{}>`_".format(title, section['secid'])



get_title_link() now returns a link with target <sectionN> instead of the named-target form <sectionN_>. This likely won’t resolve to the .. _sectionN: label and may produce a broken relative URL. Please align this with the rest of the module’s internal link strategy (e.g., sectionN_ or Sphinx :ref:).

Copilot · 2026-03-26T21:33:38Z

+#     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


The header comment’s GitHub URL appears to have a typo ("rda-python-mics" vs this repo/package name "rda_python_miscs" / "rda-python-miscs"). Also the "Title" comment says section_rst.temp but the actual filename is section.rst.temp. Please update these header metadata lines to match the real file/repo.

Copilot · 2026-03-26T21:33:38Z

 from rda_python_common.pg_file import PgFile
 from rda_python_common.pg_util import PgUtil
-
+from posix import WIFCONTINUED


The import from posix import WIFCONTINUED appears unused (no references in this module) and also makes the module non-portable on non-POSIX platforms. Please remove it unless it’s required elsewhere.

Suggested change

from posix import WIFCONTINUED

Copilot · 2026-03-26T21:33:39Z

+      clevel = section['level'] if csection else 0
+      csecid = section['secid'] if csection else ""


create_toc() uses section['level'] / section['secid'] when csection is provided, but section is not defined at that point (will raise NameError). Use csection for these values (or rename variables to avoid confusion with the later loop variable).

Suggested change

clevel = section['level'] if csection else 0

csecid = section['secid'] if csection else ""

clevel = csection['level'] if csection else 0

csecid = csection['secid'] if csection else ""

Copilot · 2026-03-26T21:33:39Z

+      # appendix A: list of examples for the parent section and its subsections
+      example = ""
      idx = 1  # used as example index
      for example in self.examples:
         opt = example['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 psecid or secid.startswith(psecid + "."):
+            example += "- `A.{}. {} Option -{} (-{}) <{}_e{}>`_\n".format(
+                        idx, option['type'], opt, option['name'], secid, idx)
         idx += 1


In create_toc(), example is initialized as a string and then reused as the loop variable (for example in self.examples), so example += ... will fail at runtime. Also psecid is referenced but never defined. Please rename the accumulator (e.g., examples_content) and use the intended section id filter variable (likely csecid).

overhaul pg_rst.py to dump proper *.rst files

8702464

zaihuaji requested a review from Copilot March 26, 2026 21:28

Copilot started reviewing on behalf of zaihuaji March 26, 2026 21:29 View session

Copilot AI reviewed Mar 26, 2026

View reviewed changes

save for claude fix

c223d9d

zaihuaji merged commit 1367c98 into main Mar 26, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

overhaul pg_rst.py to dump proper *.rst files#17

overhaul pg_rst.py to dump proper *.rst files#17
zaihuaji merged 2 commits into
mainfrom
hua-work-miscs

zaihuaji commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Copilot AI Mar 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	content += "*. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"
	content += "#. " + self.replace_option_link(ms.group(1), secid, 1) + "\n"

	content += create_toc(section) # add a local TOC for the section and its subsections
	content += self.create_toc(section) # add a local TOC for the section and its subsections

	link = "{}`{} <section{}>`_{}".format(pre, opt, secid, after)
	link = "{}`{} <section{}_>`_{}".format(pre, opt, secid, after)

		clevel = section['level'] if csection else 0
		csecid = section['secid'] if csection else ""

Conversation

zaihuaji commented Mar 26, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 26, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants