Admonition: inherit from LabeledFlowable

Author: brechtm

CHANGES.rst

@@ -53,6 +53,10 @@ New Features:
 
 Changed:
 
+* Admonition is a LabeledFlowable subclass now; this makes it possible to show
+  an icon to the left/right of the admonition text. This change will however
+  require adjustments to the admonition styles in custom stylesheets. Also,
+  the admonition style definitions in the 'sphinx' stylesheet needs more work.
 * The default for BodyPageTemplate.chapter_title_height is now ``None``, which
   creates a DownExpaningContainer for the chapter title flowables instead of
   one with a fixed height.  

src/rinoh/data/stylesheets/sphinx.rts

@@ -567,12 +567,24 @@ font_slant=ITALIC
 
 [admonition]
 inline_title=false
+label_min_width=0
+label_max_width=0
+label_spacing=0
+align_baselines=false
 space_above=9pt
 space_below=5pt
 padding_top=0
 padding_bottom=4pt
 border_top=$(thin_black_stroke)
 border_bottom=$(thin_black_stroke)
+width=fill
+
+[admonition content]
+;inline_title=false
+space_above=0
+space_below=0
+padding_top=0
+padding_bottom=0
 
 [admonition title]
 base=body

src/rinoh/flowable.py

@@ -21,7 +21,8 @@
 from itertools import chain
 from token import NAME
 
-from .attribute import Attribute, OptionSet, Bool, OverrideDefault
+from .attribute import (AcceptNoneAttributeType, Attribute, OptionSet, Bool,
+                        OverrideDefault)
 from .color import Color
 from .dimension import Dimension, PT, DimensionBase
 from .draw import ShapeStyle, Rectangle, Line, LineStyle, Stroke
@@ -513,6 +514,7 @@ def initial_state(self, container):
         flowables_iter = self.flowables(container)
         title_text = self.get_style('title', container)
         if title_text:
+            from .paragraph import Paragraph
             title = Paragraph(title_text.copy(), style='title')
             flowables_iter = chain((title, ), flowables_iter)
         return GroupedFlowablesState(self, flowables_iter)
@@ -646,11 +648,35 @@ def empty(self):
         return not self.children
 
 
+class FlowablesList(AcceptNoneAttributeType):
+    @classmethod
+    def check_type(cls, value):
+        if not (super().check_type(value) or isinstance(value, (list, tuple))):
+            return False
+        return value is None or all(isinstance(val, Flowable) for val in value)
+
+    @classmethod
+    def parse_string(cls, string, source):
+        from . import styleds, reference
+
+        locals = {}
+        locals.update(reference.__dict__)
+        locals.update(styleds.__dict__)
+        flowables = eval(string, {'__builtins__':{}}, locals)    # TODO: parse!
+        return [StaticGroupedFlowables(flowables, source=source)]
+
+    @classmethod
+    def doc_format(cls):
+        return ('Python source code that represents a list of '
+                ':class:`.Flowable`\\ s')
+
+
 class LabelPosition(OptionSet):
     values = ('left', 'right')
 
 
 class LabeledFlowableStyle(FlowableStyle):
+    label = Attribute(FlowablesList, None, 'Custom label to override the default')
     label_position = Attribute(LabelPosition, 'left', 'Where to place the label')
     label_min_width = Attribute(Dimension, 12*PT, 'Minimum label width')
     label_max_width = Attribute(Dimension, 80*PT, 'Maximum label width')
@@ -693,12 +719,19 @@ class LabeledFlowable(Flowable):
 
     def __init__(self, label, flowable, id=None, style=None, parent=None):
         super().__init__(id=id, style=style, parent=parent)
-        self.label = label
+        self._label = label     # parent is set in prepare()
         self.flowable = flowable
-        label.parent = flowable.parent = self
+        flowable.parent = self
 
     def prepare(self, flowable_target):
         super().prepare(flowable_target)
+        custom_label = self.get_style('label', flowable_target)
+        if custom_label:
+            self.label = StaticGroupedFlowables(copy(custom_label),
+                                                style='label')
+        else:
+            self.label = self._label
+        self.label.parent = self
         self.label.prepare(flowable_target)
         self.flowable.prepare(flowable_target)
 
@@ -911,6 +944,3 @@ def __init__(self, page_break=Break.ANY):
 
     def render(self, container, last_descender, state=None, **kwargs):
         return 0, 0, last_descender
-
-
-from .paragraph import Paragraph

src/rinoh/frontend/rst/nodes.py

@@ -260,8 +260,6 @@ def build_flowable(self):
 
 
 class Admonition(DocutilsGroupingNode):
-    grouped_flowables_class = rt.Admonition
-
     def children_flowables(self, skip_first=0):
         try:
             self.title
@@ -275,7 +273,9 @@ def build_flowable(self):
             custom_title = self.title.styled_text()
         except AttributeError:
             custom_title = None
-        return super().build_flowable(type=admonition_type, title=custom_title)
+        content = rt.AdmonitionFlowables(self.children_flowables())
+        return rt.Admonition(rt.DummyFlowable(), content,
+                             type=admonition_type, title=custom_title)
 
 
 class Attention(Admonition):

src/rinoh/frontend/sphinx/nodes.py

@@ -20,13 +20,13 @@
 from sphinx.ext.graphviz import render_dot
 
 from ...annotation import HyperLink
-from ...flowable import LabeledFlowable, StaticGroupedFlowables
+from ...flowable import DummyFlowable, LabeledFlowable, StaticGroupedFlowables
 from ...glossary import GlossaryTerm
-from ...image import Image, Figure
+from ...image import Image
 from ...index import IndexTerm, IndexTarget, InlineIndexTarget
 from ...paragraph import Paragraph
 from ...reference import Reference
-from ...structure import DefinitionList, List
+from ...structure import Admonition, AdmonitionFlowables, DefinitionList, List
 from ...text import SingleStyledText, MixedStyledText
 from ...util import intersperse
 from ...warnings import warn
@@ -248,8 +248,9 @@ def pop_title(items):
         children = self.children_flowables()
         first_paragraph = children[0]
         custom_title = pop_title(first_paragraph.content)
-        return self.grouped_flowables_class(children, title=custom_title,
-                                            style=subtype)
+        content = AdmonitionFlowables(children)
+        return Admonition(DummyFlowable(), content, title=custom_title,
+                          style=subtype)
 
 
 # special nodes

src/rinoh/structure.py

@@ -13,7 +13,8 @@
 from .attribute import Attribute, Bool, Integer, OverrideDefault
 from .draw import Line, LineStyle
 from .element import create_destination
-from .flowable import GroupedFlowables, StaticGroupedFlowables, WarnFlowable
+from .flowable import (GroupedFlowables, LabeledFlowableStyle,
+                       StaticGroupedFlowables, WarnFlowable)
 from .flowable import LabeledFlowable, GroupedLabeledFlowables
 from .flowable import Flowable, FlowableStyle, GroupedFlowablesStyle
 from .layout import PageBreakException
@@ -26,13 +27,14 @@
 from .strings import StringField
 from .util import NotImplementedAttribute, itemcount
 
+
 __all__ = ['Section', 'Heading', 'ListStyle', 'List', 'ListItem',
            'ListItemLabel', 'ListItemLabelStyle', 'DefinitionList',
            'Header', 'Footer',
            'TableOfContentsSection', 'TableOfContents', 'TableOfContentsStyle',
            'ListOfStyle', 'ListOfEntry', 'ListOfEntryStyle',
            'TableOfContentsEntry', 'Admonition', 'AdmonitionStyle',
-           'AdmonitionTitleParagraph',
+           'AdmonitionFlowables', 'AdmonitionTitleParagraph',
            'HorizontalRule', 'HorizontalRuleStyle', 'OutOfLineFlowables']
 
 
@@ -400,17 +402,17 @@ class ListOfEntry(ReferencingParagraph):
     style_class = ListOfEntryStyle
 
 
-class AdmonitionStyle(GroupedFlowablesStyle):
+class AdmonitionStyle(LabeledFlowableStyle):
     inline_title = Attribute(Bool, True, "Show the admonition's title inline "
                                          "with the body text, if possible")
 
 
-class Admonition(StaticGroupedFlowables):
+class Admonition(LabeledFlowable):
     style_class = AdmonitionStyle
 
-    def __init__(self, flowables, title=None, type=None,
+    def __init__(self, label, flowable, title=None, type=None,
                  id=None, style=None, parent=None):
-        super().__init__(flowables, id=id, style=style, parent=parent)
+        super().__init__(label, flowable, id=id, style=style, parent=parent)
         self.custom_title = title
         self.admonition_type = type
 
@@ -421,13 +423,16 @@ def custom_title_text(self):
     def title(self, document):
         return self.custom_title or document.get_string(self.admonition_type)
 
+
+class AdmonitionFlowables(StaticGroupedFlowables):
+
     def flowables(self, container):
-        title = self.title(container.document)
+        title = self.parent.title(container.document)
         with suppress(AttributeError):
             title = title.copy()
         flowables = super().flowables(container)
         first_flowable = next(flowables)
-        inline_title = self.get_style('inline_title', container)
+        inline_title = self.parent.get_style('inline_title', container)
         if inline_title and isinstance(first_flowable, Paragraph):
             title = MixedStyledText(title, style='inline title')
             kwargs = dict(id=first_flowable.id, style=first_flowable.style,

src/rinoh/styleds.py

@@ -32,7 +32,7 @@
 from .structure import List, ListItem, ListItemLabel, DefinitionList
 from .structure import Section, TableOfContentsSection, Heading
 from .structure import ListOfEntry
-from .structure import Admonition, AdmonitionTitleParagraph
+from .structure import Admonition, AdmonitionFlowables, AdmonitionTitleParagraph
 from .structure import TableOfContents, TableOfContentsEntry
 from .structure import OutOfLineFlowables
 from .table import TableWithCaption, Table, TableSection, TableHead, TableBody

src/rinoh/stylesheets/matcher.py

@@ -296,21 +296,28 @@
 matcher('option argument', MixedStyledText.like('option_arg'))
 
 matcher('admonition', Admonition)
-matcher('admonition title', 'admonition' / Paragraph.like('title'))
-matcher('admonition title paragraph', 'admonition' / +AdmonitionTitleParagraph)
-matcher('admonition inline title', SelectorByName('admonition')
+matcher('admonition label', 'admonition' / Flowable.like('label'))
+matcher('admonition content', 'admonition' / AdmonitionFlowables)
+matcher('admonition title', 'admonition content' / Paragraph.like('title'))
+matcher('admonition title paragraph', 'admonition content' / +AdmonitionTitleParagraph)
+matcher('admonition paragraph', 'admonition content' / Paragraph)
+matcher('admonition inline title', SelectorByName('admonition content')
                                    / ... / StyledText.like('inline title'))
 
 for admonition_type in ('attention', 'caution', 'danger', 'error', 'hint',
                         'important', 'note', 'tip', 'warning', 'seealso'):
     admonition_selector = Admonition.like(admonition_type=admonition_type)
     matcher(admonition_type + ' admonition', admonition_selector)
-    selector = admonition_selector / Paragraph.like('title')
+    matcher(admonition_type + ' admonition label', admonition_selector / Flowable.like('label'))
+    admonition_content_selector = admonition_selector / AdmonitionFlowables
+    matcher(admonition_type + ' admonition content', admonition_content_selector)
+    selector = admonition_content_selector / Paragraph.like('title')
     matcher(admonition_type + ' admonition title', selector)
     matcher(admonition_type + ' admonition title paragraph',
-            admonition_selector / +AdmonitionTitleParagraph)
+            admonition_content_selector / +AdmonitionTitleParagraph)
+    matcher(admonition_type + ' admonition paragraph', admonition_content_selector / Paragraph)
     matcher(admonition_type + ' admonition inline title',
-            admonition_selector / ... / StyledText.like('inline title'))
+            admonition_content_selector / ... / StyledText.like('inline title'))
 
 # page header and footer
 

src/rinoh/template.py

@@ -13,7 +13,6 @@
 from functools import partial
 from itertools import chain
 
-from . import styleds, reference
 from .attribute import (Bool, Integer, Attribute, AttributesDictionary,
                         RuleSet, RuleSetFile, WithAttributes, AttributeType,
                         OptionSet, AcceptNoneAttributeType, OverrideDefault,
@@ -24,7 +23,7 @@
                        PageNumberFormat)
 from .element import create_destination
 from .image import BackgroundImage, Image
-from .flowable import Flowable, StaticGroupedFlowables
+from .flowable import Flowable, FlowablesList, StaticGroupedFlowables
 from .language import Language, EN
 from .layout import (Container, DownExpandingContainer, UpExpandingContainer,
                      FlowablesContainer, FootnoteContainer, ChainedContainer,
@@ -115,27 +114,6 @@ def new_chapter_page(self, document_part, page_number, chain):
         return self.page(document_part, page_number, chain)
 
 
-class FlowablesList(AcceptNoneAttributeType):
-    @classmethod
-    def check_type(cls, value):
-        if not (super().check_type(value) or isinstance(value, (list, tuple))):
-            return False
-        return value is None or all(isinstance(val, Flowable) for val in value)
-
-    @classmethod
-    def parse_string(cls, string, source):
-        locals = {}
-        locals.update(reference.__dict__)
-        locals.update(styleds.__dict__)
-        flowables = eval(string, {'__builtins__':{}}, locals)    # TODO: parse!
-        return [StaticGroupedFlowables(flowables, source=source)]
-
-    @classmethod
-    def doc_format(cls):
-        return ('Python source code that represents a list of '
-                ':class:`.Flowable`\\ s')
-
-
 class BodyPageTemplateBase(PageTemplateBase):
     header_footer_distance = Option(Dimension, 14*PT, 'Distance of the '
                                     'header and footer to the content area')

src/rinoh/text.py

@@ -195,6 +195,7 @@ def from_tokens(cls, tokens, source):
         items = []
         while tokens.next.type:
             if tokens.next.type == NAME:
+                from .inline import InlineFlowable
                 items.append(InlineFlowable.from_tokens(tokens, source))
             elif tokens.next.type == STRING:
                 items.append(cls.text_from_tokens(tokens))
@@ -245,6 +246,7 @@ def validate(cls, value):
 
     @classmethod
     def _substitute_variables(cls, text, style):
+        from .reference import Field
         def substitute_controlchars_htmlentities(string, style=None):
             try:
                 return ControlCharacter.all[string]()
@@ -714,7 +716,3 @@ def __init__(self, text_or_items, id=None, style=SUBSCRIPT_STYLE,
 class ErrorText(SingleStyledText):
     def __init__(self, text, style=ERROR_STYLE, parent=None, source=None):
         super().__init__(text, style=style, parent=parent, source=source)
-
-
-from .reference import Field
-from .inline import InlineFlowable