From f880b29d9ae5a4d7a7499e8ed3d420ec0029b528 Mon Sep 17 00:00:00 2001
From: "lina.wolf" <lwolf@w-commerce.de>
Date: Thu, 18 Apr 2024 13:32:59 +0200
Subject: [PATCH] [BUGFIX] Warn when a directive has not title

resolves https://github.com/phpDocumentor/guides/issues/983

(cherry picked from commit 08a9c919b0190fa3610280c160db959e6e4aeda7)
---
 .../Directives/ConfvalDirective.php           |  9 +++++++
 .../confval-no-title/expected/index.html      | 24 +++++++++++++++++++
 .../expected/logs/warning.log                 |  1 +
 .../confval/confval-no-title/input/index.rst  | 12 ++++++++++
 .../plantuml-server-error/expected/index.html | 18 +++++++-------
 5 files changed, 55 insertions(+), 9 deletions(-)
 create mode 100644 tests/Integration/tests/confval/confval-no-title/expected/index.html
 create mode 100644 tests/Integration/tests/confval/confval-no-title/expected/logs/warning.log
 create mode 100644 tests/Integration/tests/confval/confval-no-title/input/index.rst

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php
index 5d8136f21..321622c9f 100644
--- a/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php
+++ b/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php
@@ -22,9 +22,11 @@
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use phpDocumentor\Guides\RestructuredText\TextRoles\GenericLinkProvider;
+use Psr\Log\LoggerInterface;
 
 use function boolval;
 use function in_array;
+use function trim;
 
 /**
  * The confval directive configuration values.
@@ -41,6 +43,7 @@ public function __construct(
         GenericLinkProvider $genericLinkProvider,
         private readonly AnchorNormalizer $anchorReducer,
         private readonly InlineParser $inlineParser,
+        private readonly LoggerInterface|null $logger = null,
     ) {
         parent::__construct($startingRule);
 
@@ -71,6 +74,12 @@ protected function processSub(
         $required = false;
         $default = null;
         $additionalOptions = [];
+        if (trim($directive->getData()) === '') {
+            if ($this->logger !== null) {
+                $this->logger->warning('A directive must have a title: ..  confval:: [some_title]', $blockContext->getLoggerInformation());
+            }
+        }
+
         if ($directive->hasOption('type')) {
             $type = $this->inlineParser->parse($directive->getOption('type')->toString(), $blockContext);
         }
diff --git a/tests/Integration/tests/confval/confval-no-title/expected/index.html b/tests/Integration/tests/confval/confval-no-title/expected/index.html
new file mode 100644
index 000000000..3a92d7bed
--- /dev/null
+++ b/tests/Integration/tests/confval/confval-no-title/expected/index.html
@@ -0,0 +1,24 @@
+<!-- content start -->
+    <div class="section" id="confval-directive">
+            <h1>Confval directive</h1>
+            <dl class="confval">
+    <dt id="confval-">
+        <code class="sig-name descname"><span class="pre"></span></code></dt>
+    <dd>
+        <div class="line-block">
+             <div class="line"><strong>Type:</strong>  <code>&quot;Hello World&quot;</code></div>
+             <div class="line"><strong>Required:</strong> true</div>
+            <div class="line"><strong>Custom Info:</strong> <strong>custom</strong></div>
+
+            </div>
+        <div class="confval-description">
+
+    <p>This is the confval <code>demo</code> content!</p>
+
+    <p>Another paragraph.</p>
+
+        </div>
+    </dd>
+</dl>
+    </div>
+<!-- content end -->
diff --git a/tests/Integration/tests/confval/confval-no-title/expected/logs/warning.log b/tests/Integration/tests/confval/confval-no-title/expected/logs/warning.log
new file mode 100644
index 000000000..07042ff0d
--- /dev/null
+++ b/tests/Integration/tests/confval/confval-no-title/expected/logs/warning.log
@@ -0,0 +1 @@
+app.WARNING: A directive must have a title
diff --git a/tests/Integration/tests/confval/confval-no-title/input/index.rst b/tests/Integration/tests/confval/confval-no-title/input/index.rst
new file mode 100644
index 000000000..97feb3863
--- /dev/null
+++ b/tests/Integration/tests/confval/confval-no-title/input/index.rst
@@ -0,0 +1,12 @@
+Confval directive
+=================
+
+.. confval::
+    :type: :php:`string`
+    :default: ``"Hello World"``
+    :required: true
+    :Custom Info: **custom**
+
+    This is the confval ``demo`` content!
+
+    Another paragraph.
diff --git a/tests/Integration/tests/graphs/plantuml-server-error/expected/index.html b/tests/Integration/tests/graphs/plantuml-server-error/expected/index.html
index ac142e833..2f55a1bda 100644
--- a/tests/Integration/tests/graphs/plantuml-server-error/expected/index.html
+++ b/tests/Integration/tests/graphs/plantuml-server-error/expected/index.html
@@ -1,11 +1,11 @@
 <!-- content start -->
-<div class="section" id="uml-directive">
-    <h1>Uml Directive</h1>
-    <figure
-            class="uml-diagram"
-            style="width: 1000"    ><figcaption>Figure 1-1: Application flow</figcaption></figure>
-    <figure
-            class="uml-diagram"
-            style="width: 1000"    ><figcaption>Figure 1-1: Application flow</figcaption></figure>
-</div>
+    <div class="section" id="uml-directive">
+            <h1>Uml Directive</h1>
+            <figure
+        class="uml-diagram"
+        style="width: 1000"    ><figcaption>Figure 1-1: Application flow</figcaption></figure>
+            <figure
+        class="uml-diagram"
+        style="width: 1000"    ><figcaption>Figure 1-1: Application flow</figcaption></figure>
+    </div>
 <!-- content end -->