[FEATURE] Make index file configurable

The index file will also be used in automatic menu
building.

As oposed to setting "input-file" not only the one file mentioned will be rendererd but all files from the directory. However the name of the input file can be changed.

Some markdown projects like to change the name of the index file. For example powermail is using
Readme.md as index file in every directory:

https://github.com/in2code-de/powermail/tree/master/Documentation

References #1108

Author: linawolf

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,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\SettingsManager;
 
 use function count;
 
@@ -32,8 +33,10 @@
  */
 final class MenuDirective extends BaseDirective
 {
-    public function __construct(private readonly ToctreeBuilder $toctreeBuilder)
-    {
+    public function __construct(
+        private readonly ToctreeBuilder $toctreeBuilder,
+        private readonly SettingsManager $settingsManager,
+    ) {
     }
 
     public function getName(): string
@@ -49,7 +52,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() ?? 'index,Index';
+        $options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);
 
         $toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
             $parserContext,

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

@@ -21,6 +21,7 @@
 use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
+use phpDocumentor\Guides\Settings\SettingsManager;
 
 /**
  * Sphinx based Toctree directive.
@@ -37,6 +38,7 @@ final class ToctreeDirective extends BaseDirective
     public function __construct(
         private readonly ToctreeBuilder $toctreeBuilder,
         private readonly Rule $startingRule,
+        private readonly SettingsManager $settingsManager,
     ) {
     }
 
@@ -52,7 +54,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() ?? 'index,Index';
+        $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,6 +21,7 @@
 use phpDocumentor\Guides\Event\PreParseProcess;
 use phpDocumentor\Guides\FileCollector;
 use phpDocumentor\Guides\Nodes\DocumentNode;
+use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\EventDispatcher\EventDispatcherInterface;
 
 use function assert;
@@ -34,6 +35,7 @@ public function __construct(
         private readonly FileCollector $fileCollector,
         private readonly CommandBus $commandBus,
         private readonly EventDispatcherInterface $eventDispatcher,
+        private readonly SettingsManager $settingsManager,
     ) {
     }
 
@@ -84,6 +86,7 @@ private function getDirectoryIndexFile(
         string $sourceFormat,
     ): string {
         $extension = $sourceFormat;
+        $indexName = $this->settingsManager->getProjectSettings()->getIndexName();
 
         // On macOS filesystems, a file-check against "index.rst"
         // using $filesystem->has() would return TRUE, when in fact
@@ -98,14 +101,23 @@ private function getDirectoryIndexFile(
             $hashedContentFromFilesystem[$itemFromFilesystem['basename']] = true;
         }
 
-        foreach (self::INDEX_FILE_NAMES as $indexName) {
+        if ($indexName !== null) {
             $indexFilename = sprintf('%s.%s', $indexName, $extension);
             if (isset($hashedContentFromFilesystem[$indexFilename])) {
                 return $indexName;
             }
+        } else {
+            foreach (self::INDEX_FILE_NAMES as $indexName) {
+                $indexFilename = sprintf('%s.%s', $indexName, $extension);
+                if (isset($hashedContentFromFilesystem[$indexFilename])) {
+                    return $indexName;
+                }
+            }
+
+            $indexName = self::INDEX_FILE_NAMES[0];
         }
 
-        $indexFilename = sprintf('%s.%s', self::INDEX_FILE_NAMES[0], $extension);
+        $indexFilename = sprintf('%s.%s', $indexName, $extension);
 
         throw new InvalidArgumentException(
             sprintf('Could not find index file "%s" in "%s"', $indexFilename, $directory),

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|null $indexName = null;
     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|null
+    {
+        return $this->indexName;
+    }
+
+    public function setIndexName(string|null $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.