解决在Sphinx扩展中查询`self.state.document.current_source`时出现docutils错误，或者更好的获取文件路径的方法

Question

考虑将通用指令作为新扩展的基础。我只会显示引发错误的代码。

import docutils.nodes
from docutils import nodes, core
import docutils.nodes
from docutils.parsers.rst import Directive, directives
from pathlib import Path

class TestDirective(Directive):
    ''' Return the last two parts of the Path for each document that is processed. Do other cool stuff.'''

    has_content = True

    standard_include_path = Path(states.__file__).parent / 'include'

    option_spec = {'file': directives.path,
                   'url': directives.uri,
                   'encoding': directives.encoding,
                   'class': directives.class_option}
    def run(self):

        # Next line is key to solving the problem
        current_source = self.state.document.current_source
        
        # Add error handling solution here

        # Do some path manipulation
        full_filepath = Path(current_source)
        filepath_no_suffix = full_filepath.with_suffix('')
        filepath = filepath_no_suffix.parts[-2:]
        
        # View the last two parts of the file path of file being processed
        # Purpose - Build a URL path; first, print path before assigning it to a variable.

        url_path = Path(*filepath)
        print("URL",url_path)

        # Other code follows to traverse docutils.nodes and extract data.
        # [...] 


def setup(app):
    # Register custom directive
    app.add_directive("testdirective", TestDirective)

假设

• conf.py 中添加的项目

  • sys.path.append(os.path.abspath('../_ext'))

  • 测试指令已添加到

    extensions

• 使用

  Sphinx 4.2.0

• 使用

  Python3.10

• 使用支持

  make build

  和

  make clean

  目标
的自定义 Makefile
• 使用

  sphinx-quickstart

  仅添加了 3 个文档；用作源目录
  • 目录结构： 来源/ 指南/ 概述.rst get_started.rst 开发者指南.rst

预期产量

总而言之，每一行都应该显示一些“URL目录/文档”

URL guides/overview7%] guides/overview
URL guides/get_started9%] guides/get_started
URL guides/developer_guide26%] guides/developer_guide

错误输出

第 1 行发生错误。 这可能是由于 Sphinx 从 conf.py 中的

rst_epilog

中引入了替换。我不确定。

URL <rst_epilog>
URL guides/get_started9%] guides/get_started
URL guides/developer_guide26%] guides/developer_guide

错误查询

在错误输出的第 1 行中，它不生成文件路径，而是生成

<rst_epilog>

。 我需要编写一些错误处理代码，以确保如果构建器遇到此类消息，它可以恢复为父文件名。 有谁知道如何解决这个问题吗？

我尝试过的

我一直在努力包含类 Include(Directive) 的一些变体，在这里：https://sphinx-docutils.readthedocs.io/en/latest/_modules/docutils/parsers/rst/directives/misc.html #

到目前为止，我尝试在出现注释“在此处添加错误处理解决方案”的地方插入以下代码，但没有任何效果。

尝试解决错误的示例：

    current_source = self.state.document.current_source
    path = directives.path(self.arguments[0])
    if path.startswith('<') and path.endswith('>'):
        _base = self.standard_include_path
        path = path[1:-1]
    else:
        _base = Path(current_source).parent
    path = utils.relative_path(None, _base/path)

但是，如果我添加上述代码，我会收到以下错误：

path = directives.path(self.arguments[0])
IndexError: list index out of range

Answer 1

作为后备方案，您可以尝试使用

document

元素“source”属性

self.state.document['source']

或内部“_source”属性

self.state.document._source

。

与内部“current_source”属性类似，它们可能是

• 文件路径
• 一个 URI
• 源的正式或非正式描述（例如标准输入或生成源字符串的实体）。
• 无

这意味着，对于没有关联文件或 URI 作为源的文档，您还需要第二个后备。