Hua work miscs

[zaihuaji]

No description provided.

[Copilot]

Pull request overview

This PR introduces reStructuredText (RST) generation support for .usg help documents by adding RST templates and a new PgRST implementation, and wires a new pgrst CLI entry point.

Changes:

• Add RST template files for index, toc, and per-section pages.
• Add PgRST implementation to parse .usg docs and render .rst output.
• Bump package version and add a new pgrst console script.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/rda_python_miscs/rst_templates/toc.rst.temp	New TOC template for generated RST docs.
src/rda_python_miscs/rst_templates/section.rst.temp	New per-section RST template.
src/rda_python_miscs/rst_templates/index.rst.temp	New index page template for generated RST docs.
src/rda_python_miscs/pg_rst.py	Adds the RST generator implementation and CLI parsing block.
src/rda_python_miscs/pg_rst.py.bck	Adds a backup/alternate RST generator implementation copy.
src/rda_python_miscs/pg_docs.py	Adds the HTML generator module (legacy-style) into this package.
pyproject.toml	Version bump and adds the pgrst console script entry.

Comments suppressed due to low confidence (1)

src/rda_python_miscs/pg_rst.py:1236

• pg_rst.py is used as a console script (pgrst), but the module does not define a main() function—only an if __name__ == '__main__': block. Add a main(argv=None) function that performs the current argument parsing + execution, and call it from the __main__ guard so both python -m ... and the entry point work.

if __name__ == '__main__':
   parser = argparse.ArgumentParser(
      description=(
         "Generate RST documentation from a structured .usg source document.\n\n"
         "OPTS and ALIAS are loaded from rda_python_<docname>/<docname>.py: "
         "the module is searched first for module-level OPTS/ALIAS variables, "
         "then for a class defined in that module that carries both as class "
         "attributes."
      ),
      formatter_class=argparse.RawDescriptionHelpFormatter,
   )
   parser.add_argument(
      'docname',
      help=(
         "Short document name, e.g. 'dsarch' or 'dsupdt'.  "
         "The module rda_python_<docname>/<docname>.py must be importable "
         "and must define OPTS (and optionally ALIAS) either at module "
         "level or as class attributes."
      ),
   )
   parser.add_argument(
      '--docdir',
      default=None,
      metavar='DIR',
      help=(
         "Root directory under which the per-document RST output directory "
         "is created (default: current working directory).  "
         "The final output lands in <docdir>/<docname>/."
      ),
   )
   args = parser.parse_args()

   opts, alias, origin = _load_opts_alias(args.docname)
   pg = PgRST()
   pg.DOCS['ORIGIN'] = origin
   if args.docdir is not None:
      pg.DOCS['DOCDIR'] = args.docdir
   pg.process_docs(args.docname, opts, alias)

---

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

[Copilot]

The --docdir help says output lands in <docdir>/<docname>/, but the implementation assigns pg.DOCS['DOCDIR'] = args.docdir and process_docs() writes directly into DOCDIR without creating a per-docname subdirectory. This is either misleading CLI documentation or a behavior bug that can cause different docs to overwrite each other. Either update the help text or change the code to write into os.path.join(docdir, docname) (and ensure the directory exists).

Suggested change

	if args.docdir is not None:
	pg.DOCS['DOCDIR'] = args.docdir
	# Determine the root directory for documentation output. If --docdir is
	# not provided, default to the current working directory. The final
	# output directory is always <docdir>/<docname>/ as documented.
	base_docdir = args.docdir if args.docdir is not None else os.getcwd()
	doc_output_dir = op.join(base_docdir, args.docname)
	os.makedirs(doc_output_dir, exist_ok=True)
	pg.DOCS['DOCDIR'] = doc_output_dir

[Copilot]

section.rst.temp uses a fixed-length underline (=====================) for the section heading. In reStructuredText, the underline must be at least as long as the title text, so this will break formatting for most real section titles. Consider adding a placeholder like __ULINE__ computed in code based on the rendered title length, or switch to a directive style that doesn’t require exact underline length.

Suggested change

	=====================
	__ULINE__

[Copilot]

toc.rst.temp uses a fixed-length underline for the __TITLE__ Guide heading. For longer document titles (e.g., PUBLISH_FILELIST Guide), the underline will be shorter than the rendered title, which is invalid RST and will render incorrectly / emit warnings. Use a computed underline (via a placeholder filled in by code) or choose a heading style that avoids fixed underline sizing.

Suggested change

	====================
	__TITLE__ Guide
	====================
	.. rubric:: __TITLE__ Guide

[Copilot]

This .bck backup file is checked into src/ and will be shipped in source distributions (and potentially wheels, depending on packaging settings). Since it appears to be an old/alternate implementation and is not importable as a module, it adds noise and can confuse maintainers. Please remove it from the package (or move it under docs/ or exclude it via packaging configuration).

[Copilot]

User-visible label text has a typo: Aliass should be Alias / Aliases. This will show up in generated HTML output.

Suggested change

	content += " (Aliass: "
	content += " (Alias{}: ".format(s)

[Copilot]

The added console script entry points to rda_python_miscs.pg_rst:main, but pg_rst.py does not define a main() function (it only has an if __name__ == '__main__': block). This will make pgrst fail at runtime when installed. Expose a main() callable (and have the __main__ block call it), or update the entry point to a function that exists.

Suggested change

"pgrst" = "rda_python_miscs.pg_rst:main"

[Copilot]

opts.insert(0, ...) returns None, so when ms matches this line sets opts to None and breaks option-link replacement (and can raise later when iterating). Prepend the match groups without using the return value (e.g., opts = [ms.groups()] + opts).

Suggested change

	if ms: opts = opts.insert(0, ms.groups())
	if ms: opts = [ms.groups()] + opts