声明在扩展额外的依赖性狮身人面像建造

Question

TL，DR：从狮身人面像的扩展，我怎么告诉sphinx-build治疗附加文件作为依赖？在我立即使用的情况下，这是扩展的源代码，但问题也同样适用于由扩展使用的一些辅助文件。

我生成使用狮身人面像自定义扩展文档。我使用sphinx-build建立的文档。例如，我使用该命令来生成HTML（这是由sphinx-quickstart产生的生成文件的命令）：

sphinx-build -b html -d _build/doctrees   . _build/html

由于我的自定义扩展与文档的源保持在一起，我想sphinx-build把它当作生成的HTML的依赖关系（和乳胶等）。所以每当我改变我的分机的源代码，我想sphinx-build再生输出。

我如何告诉sphinx-build治疗附加文件作为依赖？这是不是在toctree提到的，因为它不是源的一部分。从逻辑上讲，这应该是我做的事情从我的分机的setup功能。

---

示例扩展（my_extension.py）：

from docutils import nodes
from docutils.parsers.rst import Directive

class Foo(Directive):
    def run(self):
        node = nodes.paragraph(text='Hello world\n')
        return [node]

def setup(app):
    app.add_directive('foo', Foo)

样品源（index.rst）：

.. toctree::
   :maxdepth: 2

.. foo::

样品conf.py（sphinx-quickstart的基本输出再加上我的扩展名）：

import sys
import os
sys.path.insert(0, os.path.abspath('.'))
extensions = ['my_extension']
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = 'index'
project = 'Hello directive'
copyright = '2019, Gilles'
author = 'Gilles'
version = '1'
release = '1'
language = None
exclude_patterns = ['_build']
pygments_style = 'sphinx'
todo_include_todos = False
html_theme = 'alabaster'
html_static_path = ['_static']
htmlhelp_basename = 'Hellodirectivedoc'
latex_elements = {
}
latex_documents = [
    (master_doc, 'Hellodirective.tex', 'Hello directive Documentation',
     'Gilles', 'manual'),
]
man_pages = [
    (master_doc, 'hellodirective', 'Hello directive Documentation',
     [author], 1)
]
texinfo_documents = [
    (master_doc, 'Hellodirective', 'Hello directive Documentation',
     author, 'Hellodirective', 'One line description of project.',
     'Miscellaneous'),
]

一个解决方案的验证：

1. 运行make html（或如上sphinx-build）。
2. 修改my_extension.py通过Hello world更换Hello again。
3. 再次运行make html。
4. 生成的HTML（_build/html/index.html）现在必须包含Hello again代替Hello world的。

Answer 1

它看起来像note_dependency method in the build environment API应该做我想做的。但是，什么时候应该打电话吗？我尝试了各种events但似乎没有击中环境对象在正确的状态。什么做的工作是从一个指令调用它。

import os
from docutils import nodes
from docutils.parsers.rst import Directive
import sphinx.application

class Foo(Directive):
    def run(self):
        self.state.document.settings.env.note_dependency(__file__)
        node = nodes.paragraph(text='Hello done\n')
        return [node]

def setup(app):
    app.add_directive('foo', Foo)

如果文档中包含至少一个foo指令，它会得到标记为失效时，介绍这个指令改扩建。这是有道理的，尽管它可以得到乏味，如果一个扩展增加了许多指令或做不同的变化。我不知道是否有更好的方法。

通过Luc Van Oostenryck's autodoc-C启发。