Объявите дополнительную зависимость для sphinx-build в расширении

Question

TL,DR: от расширения Sphinx, как мне сказать sphinx-build рассматривать дополнительный файл как зависимость? В моем непосредственном случае использования это исходный код расширения, но вопрос может также относиться к некоторому вспомогательному файлу, используемому расширением.

Я генерирую документацию с помощью Sphinx, используя собственное расширение. я использую sphinx-build строить документацию. Например, я использую эту команду для генерации HTML (это команда в make-файле, сгенерированная sphinx-quickstart):

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

Поскольку мое собственное расширение поддерживается вместе с источником документации, я хочу sphinx-build рассматривать его как зависимость от сгенерированного HTML (и LaTeX и т. д.). Поэтому всякий раз, когда я изменяю исходный код моего расширения, я хочу 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 Метод в среде сборки API должен делать то, что я хочу. Но когда мне это назвать? Я пробовал разные события, но ни один из них, казалось, не попал в нужный объект. То, что сработало, было назвать это из директивы.

импорт ОС
из узлов импорта документов
из documenttils.parsers.rst Директива об импорте
импорт sphinx.application

Класс Foo(Директива):
    def run (self):
        self.state.document.settings.env.note_dependency (__ FILE__)
        node = node.paragraph(text='Hello done\n')
        возврат [узел]

настройка def (приложение):
    app.add_directive('foo', Foo)

Если документ содержит хотя бы один foo директива, она будет помечена как устаревшая, когда расширение, которое вводит эту директиву, изменится. Это имеет смысл, хотя может стать утомительным, если расширение добавляет много директив или вносит другие изменения. Я не знаю, есть ли лучший способ.

Вдохновленный автодоком Люка Ван Остенрика.

Answer 2

Насколько я знаю app.env.note_dependencyможно вызвать в пределах doctree-readчтобы добавить любой файл в качестве зависимости к читаемому в данный момент документу. Итак, в вашем случае использования я предполагаю, что это сработает:

      from typing import Any, Dict
from sphinx.application import Sphinx
import docutils.nodes as nodes


def doctree-read(app: Sphinx, doctree: nodes.document):
    app.env.note_dependency(file)


def setup(app: Sphinx):
    app.connect("doctree-read", doctree-read)