Merge pull request #1116 from phpDocumentor/task/menu

[FEATURE] Make index file configurable

Author: jaapio

packages/guides-cli/resources/schema/guides.xsd

@@ -21,6 +21,7 @@
 
         <xsd:attribute name="input" type="xsd:string"/>
         <xsd:attribute name="input-file" type="xsd:string"/>
+        <xsd:attribute name="index-name" type="xsd:string"/>
         <xsd:attribute name="output" type="xsd:string"/>
         <xsd:attribute name="input-format" type="xsd:string"/>
         <xsd:attribute name="log-path" type="xsd:string"/>

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

@@ -20,6 +20,8 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
 
 use function count;
 
@@ -28,12 +30,18 @@
  * is for display only. It does not change the position of document in the document tree and can therefore be included
  * all pages as navigation.
  *
- * By default it displays a menu of the pages on level 1 up to level 2.
+ * By default, it displays a menu of the pages on level 1 up to level 2.
  */
 final class MenuDirective extends BaseDirective
 {
-    public function __construct(private readonly ToctreeBuilder $toctreeBuilder)
-    {
+    private SettingsManager $settingsManager;
+
+    public function __construct(
+        private readonly ToctreeBuilder $toctreeBuilder,
+        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 getName(): string
@@ -49,7 +57,8 @@ public function process(
         $parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
         $options = $directive->getOptions();
         $options['glob'] = new DirectiveOption('glob', true);
-        $options['globExclude'] ??= new DirectiveOption('globExclude', 'index,Index');
+        $indexName = $this->settingsManager->getProjectSettings()->getIndexName();
+        $options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);
 
         $toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
             $parserContext,

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

@@ -21,6 +21,8 @@
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
 
 /**
  * Sphinx based Toctree directive.
@@ -33,11 +35,16 @@
  */
 final class ToctreeDirective extends BaseDirective
 {
+    private SettingsManager $settingsManager;
+
     /** @param Rule<InlineCompoundNode> $startingRule */
     public function __construct(
         private readonly ToctreeBuilder $toctreeBuilder,
         private readonly Rule $startingRule,
+        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 getName(): string
@@ -52,7 +59,8 @@ public function process(
     ): Node|null {
         $parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
         $options = $directive->getOptions();
-        $options['globExclude'] ??= new DirectiveOption('globExclude', 'index,Index');
+        $indexName = $this->settingsManager->getProjectSettings()->getIndexName();
+        $options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);
 
         $toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
             $parserContext,

packages/guides/src/DependencyInjection/GuidesExtension.php

@@ -114,6 +114,7 @@ static function ($value) {
                 ->scalarNode('theme')->end()
                 ->scalarNode('input')->end()
                 ->scalarNode('input_file')->end()
+                ->scalarNode('index_name')->end()
                 ->scalarNode('output')->end()
                 ->scalarNode('input_format')->end()
                 ->arrayNode('output_format')
@@ -237,6 +238,10 @@ public function load(array $configs, ContainerBuilder $container): void
             }
         }
 
+        if (isset($config['index_name']) && $config['index_name'] !== '') {
+            $projectSettings->setIndexName((string) $config['index_name']);
+        }
+
         if (isset($config['output'])) {
             $projectSettings->setOutput((string) $config['output']);
         }

packages/guides/src/Handlers/ParseDirectoryHandler.php

@@ -21,20 +21,28 @@
 use phpDocumentor\Guides\Event\PreParseProcess;
 use phpDocumentor\Guides\FileCollector;
 use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Settings\ProjectSettings;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\EventDispatcher\EventDispatcherInterface;
 
+use function array_map;
 use function assert;
+use function explode;
+use function implode;
 use function sprintf;
 
 final class ParseDirectoryHandler
 {
-    private const INDEX_FILE_NAMES = ['index', 'Index'];
+    private SettingsManager $settingsManager;
 
     public function __construct(
         private readonly FileCollector $fileCollector,
         private readonly CommandBus $commandBus,
         private readonly EventDispatcherInterface $eventDispatcher,
+        SettingsManager|null $settingsManager = null,
     ) {
+        // if for backward compatibility reasons no settings manager was passed, use the defaults
+        $this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
     }
 
     /** @return DocumentNode[] */
@@ -98,17 +106,20 @@ private function getDirectoryIndexFile(
             $hashedContentFromFilesystem[$itemFromFilesystem['basename']] = true;
         }
 
-        foreach (self::INDEX_FILE_NAMES as $indexName) {
-            $indexFilename = sprintf('%s.%s', $indexName, $extension);
-            if (isset($hashedContentFromFilesystem[$indexFilename])) {
+        $indexFileNames = array_map('trim', explode(',', $this->settingsManager->getProjectSettings()->getIndexName()));
+
+        $indexNamesNotFound = [];
+        foreach ($indexFileNames as $indexName) {
+            $fullIndexFilename = sprintf('%s.%s', $indexName, $extension);
+            if (isset($hashedContentFromFilesystem[$fullIndexFilename])) {
                 return $indexName;
             }
-        }
 
-        $indexFilename = sprintf('%s.%s', self::INDEX_FILE_NAMES[0], $extension);
+            $indexNamesNotFound[] = $fullIndexFilename;
+        }
 
         throw new InvalidArgumentException(
-            sprintf('Could not find index file "%s" in "%s"', $indexFilename, $directory),
+            sprintf('Could not find an index file "%s", expected file names: %s', $directory, implode(', ', $indexNamesNotFound)),
         );
     }
 }

packages/guides/src/Settings/ProjectSettings.php

@@ -24,6 +24,7 @@ final class ProjectSettings
     private string $theme = 'default';
     private string $input = 'docs';
     private string $inputFile = '';
+    private string $indexName = 'index,Index';
     private string $output = 'output';
     private string $inputFormat = 'rst';
     /** @var string[]  */
@@ -230,4 +231,16 @@ public function setIgnoredDomains(array $ignoredDomains): void
     {
         $this->ignoredDomains = $ignoredDomains;
     }
+
+    public function getIndexName(): string
+    {
+        return $this->indexName;
+    }
+
+    public function setIndexName(string $indexName): ProjectSettings
+    {
+        $this->indexName = $indexName;
+
+        return $this;
+    }
 }

tests/Integration/tests/markdown/index-name-md/expected/anotherPage.html

@@ -0,0 +1,8 @@
+<!-- content start -->
+    <div class="section" id="another-page">
+            <h1>Another Page</h1>
+
+    <p>Lorem Ipsum Dolor.</p>
+
+    </div>
+<!-- content end -->

tests/Integration/tests/markdown/index-name-md/expected/readme.html

@@ -0,0 +1,8 @@
+<!-- content start -->
+    <div class="section" id="sample-markdown-document">
+            <h1>Sample Markdown Document</h1>
+
+    <p>Lorem Ipsum</p>
+
+    </div>
+<!-- content end -->

tests/Integration/tests/markdown/index-name-md/expected/yetAnotherPage.html

@@ -0,0 +1,8 @@
+<!-- content start -->
+    <div class="section" id="yet-another-page">
+            <h1>Yet Another Page</h1>
+
+    <p>Lorem Ipsum Dolor.</p>
+
+    </div>
+<!-- content end -->

tests/Integration/tests/markdown/index-name-md/input/anotherPage.md

@@ -0,0 +1,3 @@
+# Another Page
+
+Lorem Ipsum Dolor.

tests/Integration/tests/markdown/index-name-md/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+        index-name="readme"
+>
+</guides>

tests/Integration/tests/markdown/index-name-md/input/readme.md

@@ -0,0 +1,3 @@
+# Sample Markdown Document
+
+Lorem Ipsum

tests/Integration/tests/markdown/index-name-md/input/yetAnotherPage.md

@@ -0,0 +1,3 @@
+# Yet Another Page
+
+Lorem Ipsum Dolor.