Merge pull request #462 from linawolf/titled-admonitions

Support titled and not titled admonitions

Author: jaapio

packages/guides-restructured-text/src/RestructuredText/Directives/AbstractAdmonitionDirective.php

@@ -34,6 +34,7 @@ final protected function processSub(
     ): Node|null {
         return new AdmonitionNode(
             $this->name,
+            $directive->getDataNode(),
             $this->text,
             $document->getChildren(),
         );

packages/guides-restructured-text/src/RestructuredText/Directives/AdmonitionDirective.php

@@ -53,8 +53,10 @@ protected function processSub(DocumentNode $document, Directive $directive): Nod
 
         return new AdmonitionNode(
             $name,
+            $directive->getDataNode(),
             $directive->getData(),
             $document->getChildren(),
+            true,
         );
     }
 }

packages/guides-restructured-text/src/RestructuredText/NodeRenderers/Html/AdmonitionNodeRenderer.php

@@ -48,6 +48,8 @@ public function render(Node $node, RenderContext $renderContext): string
             [
                 'name' => $node->getName(),
                 'text' => $node->getText(),
+                'title' => $node->getTitle(),
+                'isTitled' => $node->isTitled(),
                 'class' => implode(' ', $classes),
                 'node' => $node->getValue(),
             ],

packages/guides-restructured-text/src/RestructuredText/Nodes/AdmonitionNode.php

@@ -14,13 +14,14 @@
 namespace phpDocumentor\Guides\RestructuredText\Nodes;
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\Node;
 
 /** @extends CompoundNode<Node> */
 class AdmonitionNode extends CompoundNode
 {
-    /** {@inheritDoc} */
-    public function __construct(private readonly string $name, private readonly string $text, array $value)
+    /** @param Node[] $value */
+    public function __construct(private readonly string $name, private readonly InlineCompoundNode|null $title, private readonly string $text, array $value, private readonly bool $isTitled = false)
     {
         parent::__construct($value);
     }
@@ -30,8 +31,18 @@ public function getName(): string
         return $this->name;
     }
 
+    public function getTitle(): InlineCompoundNode|null
+    {
+        return $this->title;
+    }
+
     public function getText(): string
     {
         return $this->text;
     }
+
+    public function isTitled(): bool
+    {
+        return $this->isTitled;
+    }
 }

packages/guides/resources/template/html/body/admonition.html.twig

@@ -1,4 +1,5 @@
 <div class="admonition {{ name }}{{ class ? (' '~class) }}{% if node.classes %} {{ node.classesString }}{% endif %}">
-    {% if title %}<p class="admonition-title">{{ title }}</p>{% endif %}
+    {% if title and isTitled %}<p class="admonition-title">{{ renderNode(title) }}</p>{% endif %}
+    {% if title and not isTitled %}<p>{{ renderNode(title) }}</p>{% endif %}
     {{ renderNode(node) }}
 </div>

tests/Functional/tests/admonitions-contents/admonitions-contents.html

@@ -1,19 +1,12 @@
-SKIP contents of admonitions must start after the directive indicator (https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions)
 <p>Testing various supported formats:</p>
-<div class="phpdocumentor-admonition note">
-    <svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path>
-    </svg>
-    <article>
-        <p>This is the first line of content</p>
-        <p>And this is the second line</p>
-    </article>
+<div class="admonition this-is-the-title">
+    <p class="admonition-title">This is the title</p>
+    <p>And this is the second line</p>
 </div>
-<div class="phpdocumentor-admonition note">
-    <svg class="phpdocumentor-admonition__icon" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
-        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z"></path>
-    </svg>
-    <article>
-        <p>This is the first line of content</p>
-    </article>
+<div class="admonition note">
+    <p>This is the first line of content</p>
+    <p>And this is the second line</p>
+</div>
+<div class="admonition note">
+    <p>This is the first line of content</p>
 </div>

tests/Functional/tests/admonitions-contents/admonitions-contents.rst

@@ -1,5 +1,9 @@
 Testing various supported formats:
 
+.. admonition:: This is the title
+
+    And this is the second line
+
 .. note:: This is the first line of content
 
     And this is the second line

tests/Functional/tests/generic-admonition/generic-admonition.html

@@ -1,3 +1,4 @@
 <div class="admonition screencast">
+    <p class="admonition-title">Screencast</p>
     <p>Enjoy a screencast better? Watch this video: ...</p>
 </div>

tests/Integration/tests/class-directive/expected/index.html

@@ -1,7 +1,8 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-<title></title>
+    <title></title>
+
 </head>
 <body>
     <p class="special-paragraph2">Test special-paragraph 1.</p><p class="special-paragraph2">Test special-paragraph 2.</p>
@@ -15,11 +16,11 @@
 
 
 <div class="admonition note my-class">
-        
+        <p>A Note with a class</p>    
 </div>
 
 <div class="admonition note">
-        
+        <p>A note without a class</p>    
 </div>
 
 <blockquote class="highlights"><p>Block quote text.</p></blockquote>