[FEATURE] Introduce noindex option for confvals

https://sphinx-toolbox.readthedocs.io/en/stable/extensions/confval.html#directive-option-confval-noindex releases: main, 1.0
phpDocumentor · Mar 23, 2024 · b1cdc6b · b1cdc6b
1 parent 3ef4ee0
commit b1cdc6b
Show file tree

Hide file tree

Showing 10 changed files with 173 additions and 3 deletions.
diff --git a/packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig b/packages/guides-restructured-text/resources/template/html/body/directive/confval.html.twig
@@ -1,5 +1,5 @@
 <dl class="confval">
-    <dt id="{{ node.anchor }}">
+    <dt {%- if node.isNoindex == false %} id="{{ node.anchor }}"{% endif %}>
         <code class="sig-name descname"><span class="pre">{{ node.plainContent }}</span></code></dt>
     <dd>
         <div class="line-block">

diff --git a/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php b/packages/guides-restructured-text/src/RestructuredText/Directives/ConfvalDirective.php
@@ -83,6 +83,8 @@ protected function processSub(
             $type = $this->inlineParser->parse($directive->getOption('default')->toString(), $blockContext);
         }
 
+        $noindex = $directive->hasOption('noindex');
+
         foreach ($directive->getOptions() as $option) {
             if (in_array($option->getName(), ['type', 'required', 'default', 'noindex', 'name'], true)) {
                 continue;
@@ -91,6 +93,6 @@ protected function processSub(
             $additionalOptions[$option->getName()] = $this->inlineParser->parse($option->toString(), $blockContext);
         }
 
-        return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren());
+        return new ConfvalNode($id, $directive->getData(), $type, $required, $default, $additionalOptions, $collectionNode->getChildren(), $noindex);
     }
 }
diff --git a/packages/guides-restructured-text/src/RestructuredText/Nodes/ConfvalNode.php b/packages/guides-restructured-text/src/RestructuredText/Nodes/ConfvalNode.php
@@ -15,7 +15,9 @@
 
 use phpDocumentor\Guides\Nodes\CompoundNode;
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\OptionalLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 
 /**
@@ -25,7 +27,7 @@
  *
  * @extends CompoundNode<Node>
  */
-final class ConfvalNode extends CompoundNode implements PrefixedLinkTargetNode
+final class ConfvalNode extends CompoundNode implements LinkTargetNode, OptionalLinkTargetsNode, PrefixedLinkTargetNode
 {
     public const LINK_TYPE = 'std:confval';
     public const LINK_PREFIX = 'confval-';
@@ -42,6 +44,7 @@ public function __construct(
         private readonly InlineCompoundNode|null $default = null,
         private readonly array $additionalOptions = [],
         array $value = [],
+        private readonly bool $noindex = false,
     ) {
         parent::__construct($value);
     }
@@ -96,4 +99,9 @@ public function getPrefix(): string
     {
         return self::LINK_PREFIX;
     }
+
+    public function isNoindex(): bool
+    {
+        return $this->noindex;
+    }
 }
diff --git a/packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php b/packages/guides/src/Compiler/NodeTransformers/CollectLinkTargetsTransformer.php
@@ -21,6 +21,7 @@
 use phpDocumentor\Guides\Nodes\LinkTargetNode;
 use phpDocumentor\Guides\Nodes\MultipleLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\OptionalLinkTargetsNode;
 use phpDocumentor\Guides\Nodes\PrefixedLinkTargetNode;
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\ReferenceResolvers\AnchorNormalizer;
@@ -95,6 +96,10 @@ public function enterNode(Node $node, CompilerContext $compilerContext): Node
         }
 
         if ($node instanceof LinkTargetNode) {
+            if ($node instanceof OptionalLinkTargetsNode && $node->isNoindex()) {
+                return $node;
+            }
+
             $currentDocument = $this->documentStack->top();
             Assert::notNull($currentDocument);
             $anchor = $this->anchorReducer->reduceAnchor($node->getId());

diff --git a/packages/guides/src/Nodes/OptionalLinkTargetsNode.php b/packages/guides/src/Nodes/OptionalLinkTargetsNode.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\Nodes;
+
+/**
+ * Makes the implementing node an optional link target. If Noindex is true
+ * no references are generated, there is no entry in the objects index and no
+ * warning about duplicate ids.
+ *
+ * Used for example in https://sphinx-toolbox.readthedocs.io/en/stable/extensions/confval.html#directive-option-confval-noindex
+ */
+interface OptionalLinkTargetsNode extends LinkTargetNode
+{
+    public function isNoindex(): bool;
+}
diff --git a/tests/Integration/tests/confval/confval-noindex/expected/another.html b/tests/Integration/tests/confval/confval-noindex/expected/another.html
@@ -0,0 +1,27 @@
+<!-- content start -->
+    <div class="section" id="confval-directive">
+            <h1>Confval directive</h1>
+            <dl class="confval">
+    <dt>
+        <code class="sig-name descname"><span class="pre">demo</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>
+
+    <p>See option <a href="/index.html#confval-demo">demo</a>.</p>
+
+    </div>
+<!-- content end -->
diff --git a/tests/Integration/tests/confval/confval-noindex/expected/index.html b/tests/Integration/tests/confval/confval-noindex/expected/index.html
@@ -0,0 +1,36 @@
+<!-- content start -->
+    <div class="section" id="confval-directive">
+            <h1>Confval directive</h1>
+            <dl class="confval">
+    <dt id="confval-demo">
+        <code class="sig-name descname"><span class="pre">demo</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>
+
+    <p>See option <a href="/index.html#confval-demo">demo</a>.</p>
+
+            <div class="toc">
+    <ul class="menu-level">
+    <li class="toc-item">
+    <a href="/another.html#confval-directive">Confval directive</a>
+
+
+</li>
+    </ul>
+</div>
+    </div>
+<!-- content end -->
diff --git a/tests/Integration/tests/confval/confval-noindex/expected/objects.inv.json b/tests/Integration/tests/confval/confval-noindex/expected/objects.inv.json
@@ -0,0 +1,32 @@
+{
+    "std:doc": {
+        "another": [
+            "-",
+            "-",
+            "another.html",
+            "Confval directive"
+        ],
+        "index": [
+            "-",
+            "-",
+            "index.html",
+            "Confval directive"
+        ]
+    },
+    "std:label": {
+        "confval-directive": [
+            "-",
+            "-",
+            "index.html#confval-directive",
+            "Confval directive"
+        ]
+    },
+    "std:confval": {
+        "demo": [
+            "-",
+            "-",
+            "index.html#demo",
+            "demo"
+        ]
+    }
+}
diff --git a/tests/Integration/tests/confval/confval-noindex/input/another.rst b/tests/Integration/tests/confval/confval-noindex/input/another.rst
@@ -0,0 +1,15 @@
+Confval directive
+=================
+
+.. confval:: demo
+    :type: :php:`string`
+    :default: ``"Hello World"``
+    :required: true
+    :Custom Info: **custom**
+    :noindex:
+
+    This is the confval ``demo`` content!
+
+    Another paragraph.
+
+See option :confval:`demo`.
diff --git a/tests/Integration/tests/confval/confval-noindex/input/index.rst b/tests/Integration/tests/confval/confval-noindex/input/index.rst
@@ -0,0 +1,19 @@
+Confval directive
+=================
+
+.. confval:: demo
+    :type: :php:`string`
+    :default: ``"Hello World"``
+    :required: true
+    :Custom Info: **custom**
+
+    This is the confval ``demo`` content!
+
+    Another paragraph.
+
+See option :confval:`demo`.
+
+..  toctree::
+    :glob:
+
+    *