创建将其他指令包装在其中的指令

Question

我们正在尝试创建一个将其他指令包装在其中的指令。下面将举例说明：

Directives
==========

.. service_card_wrapper::

    .. service_card::

    .. service_card::

我们没有找到将“service_card”的内容渲染到“service_card_wrapper”的正确方法。我们至少需要 HTML 内容，结果如下：

<div class="service-card-wrapper">
  <div class="service-card">
    Content 1
  </div>
  <div class="service-card">
    Content 2
  </div>
</div>

这是我们的第一个代码示例，其中包含一些 Bootstrap 内容：

from docutils import nodes

from docutils.parsers.rst import Directive
from docutils.parsers.rst import directives
from sphinx.util import logging


LOG = logging.getLogger(__name__)


class service_card(nodes.General, nodes.Element):
    pass


class ServiceCard(Directive):
    node_class = service_card
    option_spec = {
        # 'service_type': directives.unchanged_required,
    }

    has_content = False

    def run(self):
        node = self.node_class()
        # node['service_type'] = self.options.get('service_type')
        return [node]

def service_card_html(self, node):
    # This method renders containers per each service of the category with all
    # links as individual list items
    data = '''
        <div class="card">
        <h5 class="card-header">Featured</h5>
        <div class="card-body">
        <h5 class="card-title">Special title treatment</h5>
        <p class="card-text">With supporting text below as a natural lead-in to additional content.</p>
        <a href="#" class="btn btn-primary">Go somewhere</a>
        </div>
        </div>'''
    self.body.append(data)
    raise nodes.SkipNode

def setup(app):
    app.add_node(service_card,
                 html=(service_card_html, None))
    app.add_directive("service_card", ServiceCard)

    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }

但是我们没有找到服务卡包装器获取此内容的正确解决方案。 有人可以帮忙吗？

我们尝试创建一个 service_card_wrapper 但我们从未得到结果。

Answer 1

您正在寻找

state.nested_parse

。您可以在文档parsers/states/rst/states.py中找到源代码。另请参阅用法此处和此处。

这是来自 docutils 源代码的签名和文档字符串：

def nested_parse(self, block, input_offset, node, match_titles=False,
                 state_machine_class=None, state_machine_kwargs=None):
    """
    Create a new StateMachine rooted at `node` and run it over the input
    `block`.
    """

我修改了你的代码。现在是以下 RST 文本

Directives
==========

.. service-card-wrapper::

    .. service-card::

    .. service-card::

给出了以下 HTML 代码，我认为它足够接近：

<div class="service-card-wrapper docutils container">
  <div class="service-card">
    <p>Service card content</p>
  </div>
  <div class="service-card">
    <p>Service card content</p>
  </div>
</div>

代码：

import docutils.nodes as nodes

from docutils.parsers.rst import Directive

from sphinx.util import logging

LOG = logging.getLogger(__name__)


class service_card(nodes.General, nodes.Element):
    pass


class ServiceCard(Directive):
    node_class = service_card
    option_spec = {
        # 'service_type': directives.unchanged_required,
    }

    has_content = False

    def run(self):
        node = self.node_class()
        # node['service_type'] = self.options.get('service_type')
        return [node]


class ServiceCardWrapper(Directive):
    has_content = True

    def run(self):
        div = nodes.container('', classes=['service-card-wrapper'], type='div')
        self.state.nested_parse(self.content, self.content_offset, div)
        return [div]


def visit_service_card(self, node):
    # This method renders containers per each service of the category with all
    # links as individual list items
    data = '''
        <div class="service-card">
        <p>Service card content</p>
        </div>'''
    self.body.append(data)


def service_card_depart(self, node):
    pass


def setup(app):
    app.add_node(service_card,
                 html=(visit_service_card, service_card_depart))
    app.add_directive("service-card", ServiceCard)
    app.add_directive("service-card-wrapper", ServiceCardWrapper)

    return {
        'version': '0.1',
        'parallel_read_safe': True,
        'parallel_write_safe': True,
    }