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

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

0 голосов
/ 04 февраля 2019

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.

1 Ответ

0 голосов
/ 06 февраля 2019

Похоже, что метод note_dependency в среде сборки API должен делать то, что я хочу.Но когда мне это назвать?Я пробовал различные события , но ни один из них, похоже, не попал в объект окружающей среды в правильном состоянии.То, что сработало, это вызвало его из директивы. 

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

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

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

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

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

...