Как добавить первый формат в узлах для директивы?

Question

Как я могу использовать первую в узлах? Например, я хочу, чтобы выходной файл icluded about.rst

class Foo(Directive): 

    def run(self): 
     return [ 
      nodes.Text("**adad**"), # <-- Must be a bold text 
      nodes.Text(".. include:: about.rst"), # <-- Must include file 
     ] 

Answer 1

Вы можете построить ViewList ваших исходных данных (одна строка для каждой записи), получить Sphinx для анализа этого содержимого, а затем вернуть узлы, которые дает вам Sphinx. Следующие работал для меня:

from docutils import nodes 
from docutils.statemachine import ViewList 
from sphinx.util.compat import Directive 
from sphinx.util.nodes import nested_parse_with_titles 

class Foo(Directive): 
    def run(self): 
     rst = ViewList() 

     # Add the content one line at a time. 
     # Second argument is the filename to report in any warnings 
     # or errors, third argument is the line number.    
     rst.append("**adad**", "fakefile.rst", 10) 
     rst.append("", "fakefile.rst", 11) 
     rst.append(".. include:: about.rst", "fakefile.rst", 12) 

     # Create a node. 
     node = nodes.section() 
     node.document = self.state.document 

     # Parse the rst. 
     nested_parse_with_titles(self.state, rst, node) 

     # And return the result. 
     return node.children 

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

я должен был сделать что-то подобное для проекта --- вместо любого (легко найти) соответствующей документации, которую я использовал source of the inbuilt autodoc extension в качестве руководства.

Answer 2

Добавление текстовых узлов с содержанием отформатирован с первого синтаксиса не помогло бы. Вам нужно создать первые узловые объекты для создания необходимого первого дерева элементов. Более того, поскольку вы пытаетесь включить другой пример в пример, вам нужно будет использовать вложенный анализ, поскольку фактический контент неизвестен заранее и не может быть жестко запрограммирован.

В run() метод первого класса директивы, self.state.nested_parse() метод можно назвать. Это первоначальная цель разобрать содержание директивы, как это:

# parse text content of this directive 
# into anonymous node element (can't be used directly in the tree) 
node = nodes.Element() 
self.state.nested_parse(self.content, self.content_offset, node) 

В вашем случае вы должны либо попытаться открыть abour.rst файл, разобрать его и добавить разобранное дерево узлов в списке результат узла или вы можете просто попробовать для запуска вложенных синтаксический анализ строковой константы с директивой include.