Hua work miscs#16
Conversation
Same-file links now use `name`_ / `text <name_>`_ syntax targeting existing .. _name: anchors instead of URL fragments (#name). Cross-file links retain URL-style anonymous hyperlinks. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Cross-file option and category links now use `text <sectionN_>`_ RST anchor references instead of URL-style section.rst hrefs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
TOC is now generated directly into index.rst via the __TOC__ placeholder in index.rst.temp. write_toc() and its toc.rst.temp dependency are removed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the RST documentation generation/templates in rda_python_miscs, simplifying the generated output (removing a standalone toc.rst) and adjusting link formatting.
Changes:
- Remove raw HTML spacing from section template output.
- Embed generated TOC content directly into
index.rstand stop generatingtoc.rst. - Update option/category link generation toward label/anchor-based references; bump package version to 2.0.5.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/rda_python_miscs/rst_templates/section.rst.temp |
Removes .. raw:: html <br> spacing from section pages. |
src/rda_python_miscs/rst_templates/index.rst.temp |
Removes .. contents::/toc doc reference and adds __TOC__ placeholder to index. |
src/rda_python_miscs/pg_rst.py |
Stops writing toc.rst, injects TOC into index, and changes link formatting logic in replace_option_link(). |
pyproject.toml |
Version bump 2.0.4 → 2.0.5. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| hash = {'TITLE' : self.DOCS['DOCTIT'], 'SECID' : section['secid'], | ||
| 'TOC' : self.create_toc()} |
There was a problem hiding this comment.
write_index() now injects self.create_toc() into the index template. create_toc() currently generates links like `... <sectionX.rst>`_ and <sectionX.rst#eN> (file/fragment URIs), which won't match the new label-based linking approach and typically won't resolve correctly in Sphinx-built HTML (it will literally point at .rst sources). Update create_toc() (or the index template expectations) to emit Sphinx-friendly cross-refs (e.g. :ref: / :doc:) targeting the existing labels (like section{secid} and e{N}) so the TOC links work after this change.
| 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) |
There was a problem hiding this comment.
replace_option_link() now emits plain reST named references (e.g. `text <section1_>`_). In Sphinx, these generally only resolve within the same document; cross-file label references should use the :ref: role (e.g. :ref:text ``) to reliably target labels defined in other .rst files. Update the link formatting here to use `:ref:` (and reference the actual target label without the trailing underscore) so cross-section option/category links resolve correctly during builds.
| 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) |
There was a problem hiding this comment.
The category keyword links are being rewritten to targets like mode_ and section{secid}_ (plain named references). If these targets are defined in other section files, Sphinx won't reliably resolve them without :ref: cross-reference roles. Consider generating :ref: links here as well (e.g. :ref:Mode Options / `:ref:`Info Options <section2>) so the references resolve across documents.
No description provided.