[FEATURE] Introduce NavigationTitle

phpDocumentor · Mar 23, 2024 · ed5812c · ed5812c
1 parent 3ef4ee0
commit ed5812c
Show file tree

Hide file tree

Showing 16 changed files with 484 additions and 2 deletions.
diff --git a/packages/guides-restructured-text/resources/config/guides-restructured-text.php b/packages/guides-restructured-text/resources/config/guides-restructured-text.php
@@ -81,6 +81,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\DateFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\DedicationFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\FieldListItemRule;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NavigationTitleFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NocommentsFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\NosearchFieldListItemRule;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\FieldList\OrganizationFieldListItemRule;
@@ -320,6 +321,9 @@
         ->set(DedicationFieldListItemRule::class)
         ->tag('phpdoc.guides.parser.rst.fieldlist')
 
+        ->set(NavigationTitleFieldListItemRule::class)
+        ->tag('phpdoc.guides.parser.rst.fieldlist')
+
         ->set(NocommentsFieldListItemRule::class)
         ->tag('phpdoc.guides.parser.rst.fieldlist')
 

diff --git a/...xt/src/RestructuredText/Parser/Productions/FieldList/NavigationTitleFieldListItemRule.php b/...xt/src/RestructuredText/Parser/Productions/FieldList/NavigationTitleFieldListItemRule.php
@@ -0,0 +1,34 @@
+<?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\RestructuredText\Parser\Productions\FieldList;
+
+use phpDocumentor\Guides\Nodes\FieldLists\FieldListItemNode;
+use phpDocumentor\Guides\Nodes\Metadata\MetadataNode;
+use phpDocumentor\Guides\Nodes\Metadata\NavigationTitleNode;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+
+use function strtolower;
+
+final class NavigationTitleFieldListItemRule implements FieldListItemRule
+{
+    public function applies(FieldListItemNode $fieldListItemNode): bool
+    {
+        return strtolower($fieldListItemNode->getTerm()) === 'navigation-title';
+    }
+
+    public function apply(FieldListItemNode $fieldListItemNode, BlockContext $blockContext): MetadataNode
+    {
+        return new NavigationTitleNode($fieldListItemNode->getPlaintextContent());
+    }
+}
diff --git a/packages/guides/src/Compiler/NodeTransformers/DocumentEntryRegistrationTransformer.php b/packages/guides/src/Compiler/NodeTransformers/DocumentEntryRegistrationTransformer.php
@@ -44,7 +44,7 @@ public function leaveNode(Node $node, CompilerContext $compilerContext): Node|nu
             $this->logger->warning('Document has no title', $compilerContext->getLoggerInformation());
         }
 
-        $entry = new DocumentEntryNode($node->getFilePath(), $node->getTitle() ?? TitleNode::emptyNode(), $node->isRoot());
+        $entry = new DocumentEntryNode($node->getFilePath(), $node->getTitle() ?? TitleNode::emptyNode(), $node->isRoot(), $node->getNavigationTitle() ?? $node->getFilePath());
         $compilerContext->getProjectNode()->addDocumentEntry($entry);
 
         return $node->setDocumentEntry($entry);

diff --git a/...s/src/Compiler/NodeTransformers/MenuNodeTransformers/InternalMenuEntryNodeTransformer.php b/...s/src/Compiler/NodeTransformers/MenuNodeTransformers/InternalMenuEntryNodeTransformer.php
@@ -19,6 +19,7 @@
 use phpDocumentor\Guides\Nodes\Menu\MenuNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use Psr\Log\LoggerInterface;
 
@@ -66,7 +67,7 @@ protected function handleMenuEntry(MenuNode $currentMenu, MenuEntryNode $entryNo
             $documentEntriesInTree[] = $documentEntry;
             $newEntryNode = new InternalMenuEntryNode(
                 $documentEntry->getFile(),
-                $entryNode->getValue() ?? $documentEntry->getTitle(),
+                $entryNode->getValue() ?? TitleNode::fromString($documentEntry->getNavigationTitle()),
                 [],
                 false,
                 1,

diff --git a/packages/guides/src/Nodes/DocumentNode.php b/packages/guides/src/Nodes/DocumentNode.php
@@ -19,6 +19,7 @@
 use phpDocumentor\Guides\Nodes\DocumentTree\SectionEntryNode;
 use phpDocumentor\Guides\Nodes\Menu\TocNode;
 use phpDocumentor\Guides\Nodes\Metadata\MetadataNode;
+use phpDocumentor\Guides\Nodes\Metadata\NavigationTitleNode;
 
 use function array_filter;
 use function max;
@@ -52,6 +53,8 @@ final class DocumentNode extends CompoundNode
     private int $maxFootnoteNumber = 0;
     private int $lastReturnedAnonymousFootnoteNumber = -1;
 
+    private string|null $navigationTitle = null;
+
     /**
      * Variables are replacements in a document or project.
      *
@@ -97,6 +100,19 @@ public function getNodes(string $nodeType = Node::class): array
         return array_filter($this->value, static fn ($node): bool => $node instanceof $nodeType);
     }
 
+    public function getNavigationTitle(): string|null
+    {
+        if ($this->navigationTitle !== null) {
+            return $this->navigationTitle;
+        }
+
+        if ($this->getTitle() instanceof TitleNode) {
+            return $this->getTitle()->toString();
+        }
+
+        return null;
+    }
+
     public function getPageTitle(): string|null
     {
         if ($this->metaTitle !== null) {
@@ -132,6 +148,10 @@ public function setMetaTitle(string $metaTitle): void
 
     public function addHeaderNode(MetadataNode $node): void
     {
+        if ($node instanceof NavigationTitleNode) {
+            $this->navigationTitle = $node->getValue();
+        }
+
         $this->headerNodes[] = $node;
     }
 

diff --git a/packages/guides/src/Nodes/DocumentTree/DocumentEntryNode.php b/packages/guides/src/Nodes/DocumentTree/DocumentEntryNode.php
@@ -30,7 +30,13 @@ public function __construct(
         private readonly string $file,
         private readonly TitleNode $titleNode,
         private readonly bool $isRoot = false,
+        private string $navigationTitle = '',
     ) {
+        if ($this->navigationTitle !== '') {
+            return;
+        }
+
+        $this->navigationTitle = $titleNode->toString();
     }
 
     public function getTitle(): TitleNode
@@ -81,4 +87,9 @@ public function isRoot(): bool
     {
         return $this->isRoot;
     }
+
+    public function getNavigationTitle(): string
+    {
+        return $this->navigationTitle;
+    }
 }
diff --git a/packages/guides/src/Nodes/Metadata/NavigationTitleNode.php b/packages/guides/src/Nodes/Metadata/NavigationTitleNode.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\Metadata;
+
+/**
+ * The organization element contains the name of document author's organization,
+ * or the organization responsible for the document.
+ */
+final class NavigationTitleNode extends MetadataNode
+{
+    public function __construct(string $plaintext)
+    {
+        parent::__construct($plaintext);
+    }
+}
diff --git a/tests/Integration/tests-full/bootstrap/bootstrap-navigation-title/expected/anotherPage.html b/tests/Integration/tests-full/bootstrap/bootstrap-navigation-title/expected/anotherPage.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html class="no-js" lang="en">
+<head>
+    <title>Another Page - Bootstrap Theme</title>
+    <!-- Required meta tags -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
+</head>
+<body>
+<header class="">
+
+<nav class="navbar navbar-expand-lg navbar-dark bg-primary">
+    <div class="container">
+
+        <a class="navbar-brand" href="#">Navbar</a>
+        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
+            <span class="navbar-toggler-icon"></span>
+        </button>
+        <div class="collapse navbar-collapse" id="navbarSupportedContent">
+
+
+<ul class="navbar-nav me-auto mb-2 mb-lg-0">
+    <li class="nav-item">
+                <a href="/anotherPage.html" class="nav-link current active" aria-current="page"  >
+            Another Page
+        </a>
+        </li><li class="nav-item">
+                <a href="/somePage.html" class="nav-link" >
+            Some Page
+        </a>
+        </li><li class="nav-item">
+                <a href="/yetAnotherPage.html" class="nav-link" >
+            Yet Another Page
+        </a>
+        </li></ul>
+
+
+                    </div>
+    </div>
+</nav>
+</header>
+<main id="main-content">
+    <div class="container">
+        <div class="container">
+            <div class="row">
+                <div class="col-lg-3">
+                                <nav class="nav flex-column">
+                <ul class="menu-level-main">
+    <li><a href="/anotherPage.html"
+           class="nav-link current active" aria-current="page" >
+            Another Page
+                </a></li>
+    <li><a href="/somePage.html"
+           class="nav-link">
+            Some Page
+                </a></li>
+    <li><a href="/yetAnotherPage.html"
+           class="nav-link">
+            Yet Another Page
+                </a></li>
+            </ul>
+
+</nav>
+
+
+                </div>
+                <div class="col-lg-9">
+
+<nav aria-label="breadcrumb">
+    <ol class="breadcrumb">
+        <li class="breadcrumb-item"><a href="/index.html">Document Title</a></li>
+        <li class="breadcrumb-item"><a href="/anotherPage.html">Another Page</a></li>
+            </ol>
+</nav>
+
+                    <!-- content start -->
+
+
+<div class="section" id="another-page">
+            <h1>Another Page</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+    </div>
+
+                    <!-- content end -->
+                </div>
+            </div>
+        </div>
+    </div>
+</main>
+                <footer class="bg-primary text-light">
+            <div class="container">
+                <p>Generated by <a href="https://www.phpdoc.org/">phpDocumentor</a>.</p>
+</div>
+        </footer>
+
+<!-- Optional JavaScript; choose one of the two! -->
+
+<!-- Option 1: Bootstrap Bundle with Popper -->
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
+
+<!-- Option 2: Separate Popper and Bootstrap JS -->
+<!--
+<script src="https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js" integrity="sha384-IQsoLXl5PILFhosVNubq5LC7Qb9DXgDA9i+tQ8Zj3iwWAwPtgFTxbJ8NT4GN1R8p" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.min.js" integrity="sha384-cVKIPhGWiC2Al4u+LWgxfKTRIcfu0JTxR+EQDz/bgldoEyl4H0zUF0QKbrJ0EcQF" crossorigin="anonymous"></script>
+-->
+</body>
+</html>
diff --git a/tests/Integration/tests-full/bootstrap/bootstrap-navigation-title/expected/index.html b/tests/Integration/tests-full/bootstrap/bootstrap-navigation-title/expected/index.html
@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html class="no-js" lang="en">
+<head>
+    <title>Document Title - Bootstrap Theme</title>
+    <!-- Required meta tags -->
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+
+    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-EVSTQN3/azprG1Anm3QDgpJLIm9Nao0Yz1ztcQTwFspd3yD65VohhpuuCOmLASjC" crossorigin="anonymous">
+</head>
+<body>
+<header class="">
+
+<nav class="navbar navbar-expand-lg navbar-dark bg-primary">
+    <div class="container">
+
+        <a class="navbar-brand" href="#">Navbar</a>
+        <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
+            <span class="navbar-toggler-icon"></span>
+        </button>
+        <div class="collapse navbar-collapse" id="navbarSupportedContent">
+
+
+<ul class="navbar-nav me-auto mb-2 mb-lg-0">
+    <li class="nav-item">
+                <a href="/anotherPage.html" class="nav-link" >
+            Another Page
+        </a>
+        </li><li class="nav-item">
+                <a href="/somePage.html" class="nav-link" >
+            Some Page
+        </a>
+        </li><li class="nav-item">
+                <a href="/yetAnotherPage.html" class="nav-link" >
+            Yet Another Page
+        </a>
+        </li></ul>
+
+
+                    </div>
+    </div>
+</nav>
+</header>
+<main id="main-content">
+    <div class="container">
+        <div class="container">
+            <div class="row">
+                <div class="col-lg-3">
+                                <nav class="nav flex-column">
+                <ul class="menu-level-main">
+    <li><a href="/anotherPage.html"
+           class="nav-link">
+            Another Page
+                </a></li>
+    <li><a href="/somePage.html"
+           class="nav-link">
+            Some Page
+                </a></li>
+    <li><a href="/yetAnotherPage.html"
+           class="nav-link">
+            Yet Another Page
+                </a></li>
+            </ul>
+
+</nav>
+
+
+                </div>
+                <div class="col-lg-9">
+
+<nav aria-label="breadcrumb">
+    <ol class="breadcrumb">
+        <li class="breadcrumb-item"><a href="/index.html">Document Title</a></li>
+            </ol>
+</nav>
+
+                    <!-- content start -->
+
+
+<div class="section" id="document-title">
+            <h1>Document Title</h1>
+
+            <p>Lorem Ipsum Dolor.</p>
+
+    </div>
+
+                    <!-- content end -->
+                </div>
+            </div>
+        </div>
+    </div>
+</main>
+                <footer class="bg-primary text-light">
+            <div class="container">
+                <p>Generated by <a href="https://www.phpdoc.org/">phpDocumentor</a>.</p>
+</div>
+        </footer>
+
+<!-- Optional JavaScript; choose one of the two! -->
+
+<!-- Option 1: Bootstrap Bundle with Popper -->
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.bundle.min.js" integrity="sha384-MrcW6ZMFYlzcLA8Nl+NtUVF0sA7MsXsP1UyJoMp4YLEuNSfAP+JcXn/tWtIaxVXM" crossorigin="anonymous"></script>
+
+<!-- Option 2: Separate Popper and Bootstrap JS -->
+<!--
+<script src="https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js" integrity="sha384-IQsoLXl5PILFhosVNubq5LC7Qb9DXgDA9i+tQ8Zj3iwWAwPtgFTxbJ8NT4GN1R8p" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.min.js" integrity="sha384-cVKIPhGWiC2Al4u+LWgxfKTRIcfu0JTxR+EQDz/bgldoEyl4H0zUF0QKbrJ0EcQF" crossorigin="anonymous"></script>
+-->
+</body>
+</html>