diff --git a/pyproject.toml b/pyproject.toml index 5da10ba..be749ca 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta" [project] name = "rda_python_miscs" -version = "2.0.4" +version = "2.0.5" authors = [ { name="Zaihua Ji", email="zji@ucar.edu" }, ] diff --git a/src/rda_python_miscs/pg_rst.py b/src/rda_python_miscs/pg_rst.py index eeabce3..c683ead 100755 --- a/src/rda_python_miscs/pg_rst.py +++ b/src/rda_python_miscs/pg_rst.py @@ -129,7 +129,7 @@ def process_docs(self, docname, opts, alias): 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.rst`` per + writes ``index.rst`` and one ``section.rst`` per section into ``DOCDIR``. Args: @@ -155,8 +155,6 @@ def process_docs(self, docname, opts, alias): else: self.write_index(self.sections[0]) - self.write_toc() - for section in self.sections: self.write_section(section) @@ -404,29 +402,17 @@ def init_example(self, opt, desc): 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 @@ def replace_option_link(self, line, csecid, ptype=None, dtype=None): """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 `_ ``. + All links use RST named anchor references (`` `name`_ `` or + `` `text `_ ``) 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 @@ def replace_option_link(self, line, csecid, ptype=None, dtype=None): 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 @@ def replace_option_link(self, line, csecid, ptype=None, dtype=None): 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 @@ def replace_option_link(self, line, csecid, ptype=None, dtype=None): 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 = "{}`{} `_{}".format(pre, opt, after) else: - link = "{}`{} `_{}".format(pre, opt, secid, after) + link = "{}`{} `_{}".format(pre, opt, secid, after) line = line.replace(replace, link) ms = re.search(r'(https*://\S+)(\.|\,)', line) diff --git a/src/rda_python_miscs/rst_templates/index.rst.temp b/src/rda_python_miscs/rst_templates/index.rst.temp index be167ed..9f6bcc2 100644 --- a/src/rda_python_miscs/rst_templates/index.rst.temp +++ b/src/rda_python_miscs/rst_templates/index.rst.temp @@ -15,15 +15,10 @@ 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__ \ No newline at end of file + section__SECID__ + +__TOC__ \ No newline at end of file diff --git a/src/rda_python_miscs/rst_templates/section.rst.temp b/src/rda_python_miscs/rst_templates/section.rst.temp index 063facf..c80b7dd 100644 --- a/src/rda_python_miscs/rst_templates/section.rst.temp +++ b/src/rda_python_miscs/rst_templates/section.rst.temp @@ -16,8 +16,5 @@ __SECID__ - __TITLE__ __SECTION__ -.. raw:: html - -
:ref:`Back to Top ` \ No newline at end of file