[FEATURE] Add option to create an automatic menu

For now all Document entries are added to the root document entry. In a follow up I plan to create a nested menu as well References #1108
phpDocumentor · Oct 3, 2024 · c9e27a0 · c9e27a0
1 parent 9499293
commit c9e27a0
Show file tree

Hide file tree

Showing 23 changed files with 623 additions and 7 deletions.
diff --git a/packages/guides-cli/resources/schema/guides.xsd b/packages/guides-cli/resources/schema/guides.xsd
@@ -31,6 +31,7 @@
         <xsd:attribute name="theme" type="xsd:string"/>
         <xsd:attribute name="default-code-language" type="xsd:string"/>
         <xsd:attribute name="links-are-relative" type="xsd:string"/>
+        <xsd:attribute name="automatic-menu" type="xsd:string"/>
         <xsd:attribute name="max-menu-depth" type="xsd:int"/>
 
     </xsd:complexType>

diff --git a/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php b/packages/guides-markdown/src/Markdown/MarkupLanguageParser.php
@@ -24,6 +24,8 @@
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\Node;
 use phpDocumentor\Guides\ParserContext;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\Log\LoggerInterface;
 use RuntimeException;
 
@@ -40,16 +42,21 @@ final class MarkupLanguageParser implements MarkupLanguageParserInterface
 
     private DocumentNode|null $document = null;
 
+    private SettingsManager $settingsManager;
+
     /** @param iterable<ParserInterface<Node>> $parsers */
     public function __construct(
         private readonly LoggerInterface $logger,
         private readonly iterable $parsers,
+        SettingsManager|null $settingsManager,
     ) {
         $cmEnvironment = new CommonMarkEnvironment(['html_input' => 'strip']);
         $cmEnvironment->addExtension(new CommonMarkCoreExtension());
         $cmEnvironment->addExtension(new TableExtension());
         $cmEnvironment->addExtension(new AutolinkExtension());
         $this->markdownParser = new MarkdownParser($cmEnvironment);
+        // if for backward compatibility reasons no settings manager was passed, use the defaults
+        $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
     }
 
     public function supports(string $inputFormat): bool
@@ -69,7 +76,7 @@ public function parse(ParserContext $parserContext, string $contents): DocumentN
     private function parseDocument(NodeWalker $walker, string $hash): DocumentNode
     {
         $document = new DocumentNode($hash, ltrim($this->getParserContext()->getCurrentAbsolutePath(), '/'));
-        $document->setOrphan(true);
+        $document->setOrphan(!$this->settingsManager->getProjectSettings()->isAutomaticMenu());
         $this->document = $document;
 
         while ($event = $walker->next()) {

diff --git a/packages/guides/src/Compiler/Passes/AutomaticMenuPass.php b/packages/guides/src/Compiler/Passes/AutomaticMenuPass.php
@@ -0,0 +1,63 @@
+<?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\Compiler\Passes;
+
+use phpDocumentor\Guides\Compiler\CompilerContextInterface;
+use phpDocumentor\Guides\Compiler\CompilerPass;
+use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Settings\SettingsManager;
+
+final class AutomaticMenuPass implements CompilerPass
+{
+    public function __construct(
+        private readonly SettingsManager $settingsManager,
+    ) {
+    }
+
+    public function getPriority(): int
+    {
+        return 20; // must be run very late
+    }
+
+    /**
+     * @param DocumentNode[] $documents
+     *
+     * @return DocumentNode[]
+     */
+    public function run(array $documents, CompilerContextInterface $compilerContext): array
+    {
+        if (!$this->settingsManager->getProjectSettings()->isAutomaticMenu()) {
+            return $documents;
+        }
+
+        $projectNode = $compilerContext->getProjectNode();
+        $rootDocumentEntry = $projectNode->getRootDocumentEntry();
+        foreach ($documents as $documentNode) {
+            if ($documentNode->isOrphan()) {
+                // Do not add orphans to the automatic menu
+                continue;
+            }
+
+            if ($documentNode->isRoot()) {
+                continue;
+            }
+
+            $documentEntry = $projectNode->getDocumentEntry($documentNode->getFilePath());
+            $documentEntry->setParent($rootDocumentEntry);
+            $rootDocumentEntry->addChild($documentEntry);
+        }
+
+        return $documents;
+    }
+}
diff --git a/packages/guides/src/Compiler/Passes/GlobalMenuPass.php b/packages/guides/src/Compiler/Passes/GlobalMenuPass.php
@@ -30,6 +30,7 @@
 
 use function array_map;
 use function assert;
+use function sizeof;
 
 use const PHP_INT_MAX;
 
@@ -78,11 +79,27 @@ public function run(array $documents, CompilerContextInterface $compilerContext)
             $menuNodes[] = $menuNode->withCaption($tocNode->getCaption());
         }
 
+        if ($this->settingsManager->getProjectSettings()->isAutomaticMenu() && sizeof($menuNodes) === 0) {
+            $menuNodes[] = $this->getNavMenuNodeFromDocumentEntries($compilerContext);
+        }
+
         $projectNode->setGlobalMenues($menuNodes);
 
         return $documents;
     }
 
+    private function getNavMenuNodeFromDocumentEntries(CompilerContextInterface $compilerContext): NavMenuNode
+    {
+        $menuEntries = [];
+        $rootDocumentEntry = $compilerContext->getProjectNode()->getRootDocumentEntry();
+        foreach ($rootDocumentEntry->getChildren() as $documentEntryNode) {
+            $newMenuEntry = new InternalMenuEntryNode($documentEntryNode->getFile(), $documentEntryNode->getTitle(), [], false, 1);
+            $menuEntries[] = $newMenuEntry;
+        }
+
+        return new NavMenuNode($menuEntries);
+    }
+
     private function getNavMenuNodefromTocNode(CompilerContextInterface $compilerContext, TocNode $tocNode, string|null $menuType = null): NavMenuNode
     {
         $self = $this;

diff --git a/packages/guides/src/Compiler/Passes/ToctreeValidationPass.php b/packages/guides/src/Compiler/Passes/ToctreeValidationPass.php
@@ -18,13 +18,20 @@
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
 use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\Log\LoggerInterface;
 
 final class ToctreeValidationPass implements CompilerPass
 {
+    private SettingsManager $settingsManager;
+
     public function __construct(
         private readonly LoggerInterface $logger,
+        SettingsManager|null $settingsManager = null,
     ) {
+        // if for backward compatibility reasons no settings manager was passed, use the defaults
+        $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
     }
 
     public function getPriority(): int
@@ -39,6 +46,10 @@ public function getPriority(): int
      */
     public function run(array $documents, CompilerContextInterface $compilerContext): array
     {
+        if ($this->settingsManager->getProjectSettings()->isAutomaticMenu()) {
+            return $documents;
+        }
+
         $projectNode = $compilerContext->getProjectNode();
 
         foreach ($documents as $document) {

diff --git a/packages/guides/src/DependencyInjection/GuidesExtension.php b/packages/guides/src/DependencyInjection/GuidesExtension.php
@@ -143,6 +143,7 @@ static function ($value) {
                 ->scalarNode('show_progress')->end()
                 ->scalarNode('links_are_relative')->end()
                 ->scalarNode('max_menu_depth')->end()
+                ->scalarNode('automatic_menu')->end()
                 ->arrayNode('base_template_paths')
                     ->defaultValue([])
                     ->scalarPrototype()->end()
@@ -278,6 +279,10 @@ public function load(array $configs, ContainerBuilder $container): void
             $projectSettings->setMaxMenuDepth((int) $config['max_menu_depth']);
         }
 
+        if (isset($config['automatic_menu'])) {
+            $projectSettings->setAutomaticMenu((bool) $config['automatic_menu']);
+        }
+
         if (isset($config['default_code_language'])) {
             $projectSettings->setDefaultCodeLanguage((string) $config['default_code_language']);
         }

diff --git a/packages/guides/src/Settings/ProjectSettings.php b/packages/guides/src/Settings/ProjectSettings.php
@@ -35,6 +35,7 @@ final class ProjectSettings
     private bool $linksRelative = false;
     private string $defaultCodeLanguage = '';
     private int $maxMenuDepth = 0;
+    private bool $automaticMenu = false;
 
     /** @var string[] */
     private array $ignoredDomains = [];
@@ -243,4 +244,16 @@ public function setIndexName(string $indexName): ProjectSettings
 
         return $this;
     }
+
+    public function isAutomaticMenu(): bool
+    {
+        return $this->automaticMenu;
+    }
+
+    public function setAutomaticMenu(bool $automaticMenu): ProjectSettings
+    {
+        $this->automaticMenu = $automaticMenu;
+
+        return $this;
+    }
 }
diff --git a/tests/Integration/tests-full/markdown-full/default-menu-md/expected/anotherPage.html b/tests/Integration/tests-full/markdown-full/default-menu-md/expected/anotherPage.html
@@ -19,7 +19,22 @@
             <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="#" 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>
@@ -29,7 +44,23 @@
         <div class="container">
             <div class="row">
                 <div class="col-lg-3">
-
+                                <nav class="nav flex-column">
+        <ul class="menu-level-main">
+        <li>
+            <a href="#"
+               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">
 

diff --git a/tests/Integration/tests-full/markdown-full/default-menu-md/expected/index.html b/tests/Integration/tests-full/markdown-full/default-menu-md/expected/index.html
@@ -19,7 +19,22 @@
             <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>
@@ -29,7 +44,23 @@
         <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">
 

diff --git a/tests/Integration/tests-full/markdown-full/default-menu-md/expected/somePage.html b/tests/Integration/tests-full/markdown-full/default-menu-md/expected/somePage.html
@@ -19,7 +19,22 @@
             <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="#" class="nav-link current active" aria-current="page">
+                Some Page
+            </a>
+        </li><li class="nav-item">
+            <a href="yetAnotherPage.html" class="nav-link">
+                Yet Another Page
+            </a>
+        </li></ul>
+
                     </div>
     </div>
 </nav>
@@ -29,7 +44,23 @@
         <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="#"
+               class="nav-link current active" aria-current="page">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">
 

diff --git a/tests/Integration/tests-full/markdown-full/default-menu-md/input/guides.xml b/tests/Integration/tests-full/markdown-full/default-menu-md/input/guides.xml
@@ -5,6 +5,7 @@
         theme="bootstrap"
         input-format="md"
         links-are-relative="1"
+        automatic-menu="true"
 >
     <extension class="phpDocumentor\Guides\Bootstrap"/>
 </guides>