python-sphinx - 转义索引指令中的特殊字符

Question

我正在为使用 Sphinx 的 Prolog 系统实现生成文档。 Prolog 语言包括合取和析取控制结构，它们分别由复合术语 (',')/2 和 (;)/2 表示。

但由于存在逗号和分号，以下索引指令不会生成正确的条目:

.. index:: (',')/2

.. index:: (;)/2

到目前为止，我一直无法找到字符转义解决方案。我对 Prolog !/0 控制构造也有同样的问题，但我通过编写找到了一个解决方法:

.. index:: !!/0

尝试使用反斜杠无济于事。是否支持在我缺少的指令中转义特殊字符？是否有任何替代解决方案来拥有 (',')/2、(;)/2 和 !/0 索引条目？

Answer 1

< (;)/2 >

(;)/2取决于 IndexEntries 类使用的 split_into 函数。

• 我猜:value.split(';', n - 1) -> value.split('; ', n - 1)
• 我对 #8904 发表了评论。
• 重写这段代码对你来说似乎很容易。

sphinx/util/init.py ( Sphinx 4.2.0 )

365
366 def split_into(n: int, type: str, value: str) -> List[str]:
367     """Split an index entry into a given number of parts at semicolons."""
368     parts = [x.strip() for x in value.split(';', n - 1)]
369     if sum(1 for part in parts if part) < n:
370         raise ValueError('invalid %s index entry %r' % (type, value))
371     return parts
372

< !!/0 >

!!/0取决于 process_index_entry 函数和索引指令/角色使用的另一个函数。

• 解决方法是使用 !!!/0

sphinx/util/nodes.py ( Sphinx 4.2.0 )

363
364 def process_index_entry(entry: str, targetid: str
365                         ) -> List[Tuple[str, str, str, str, Optional[str]]]:
366     from sphinx.domains.python import pairindextypes
367
368     indexentries: List[Tuple[str, str, str, str, Optional[str]]] = []
369     entry = entry.strip()
370     oentry = entry
371     main = ''
372     if entry.startswith('!'):
373         main = 'main'
374         entry = entry[1:].lstrip()
375     for type in pairindextypes:
376         if entry.startswith(type + ':'):
377             value = entry[len(type) + 1:].strip()
378             value = pairindextypes[type] + '; ' + value
379             indexentries.append(('pair', value, targetid, main, None))
380             break
381     else:

sphinx/domains/index.py ( Sphinx 4.2.0 )

 62
 63 class IndexDirective(SphinxDirective):
 64     """
 65     Directive to add entries to the index.
 66     """
...
 90         for entry in arguments:
 91             indexnode['entries'].extend(process_index_entry(entry, targetnode['ids'][0]))
 92         return [indexnode, targetnode]
...
 94
 95 class IndexRole(ReferenceRole):
 96     def run(self) -> Tuple[List[Node], List[system_message]]:
...
102         else:
103             # otherwise we just create a single entry
104             if self.target.startswith('!'):
105                 title = self.title[1:]
106                 entries = [('single', self.target[1:], target_id, 'main', None)]
107             else:

其他

理想但困难的解决方案是开发sphinx/domains/prolog.py .