Merge pull request #586 from phpDocumentor/feature/paths

[FEATURE] Configure inventories via guides.xml

Author: jaapio

docs/configuration.rst

@@ -6,17 +6,11 @@ Configuration
 
 This library can be configured in two ways:
 
-1. ``guides.xml`` in the current directory. This file configures the Guides
-   library (which extensions to load) and can configure default values for
-   the project specific settings.
-2. ``settings.php`` in the source files directory. This file can contain
-   project/manual specific settings.
-
-In most cases, you should do everything in the ``guides.xml`` file.
-Documentations that compile the docs for a collection of projects might
-want to use both config options. For instance, the ``guides.xml`` can
-configure the documentation theme, whereas the ``settings.php`` configures
-the title and version of each specific project.
+1.  ``guides.xml`` in the current directory. This file configures the Guides
+    library (which extensions to load) and can configure default values for
+    the project specific settings.
+2.  ``guides.xml`` in the parent of the vendor directory. Options are
+    overridden by the first location
 
 Global configuration
 ====================
@@ -52,24 +46,3 @@ you want to use the Bootstrap HTML theme, use this configuration:
     </guides>
 
 See the ``guides.xsd`` file for all available config options.
-
-Per-manual configuration
-========================
-
-If you need different settings for different manuals you are building,
-you can do so by creating a ``settings.php`` file in the input directory
-of the manual you are building (that is the directory you would specify
-as a first argument to the CLI).
-
-That file needs to return an `array`, and typically looks as
-follows:
-
-..  code-block:: php
-
-    <?php
-
-    return [
-        'title' => 'My Project',
-        'version' => '3.1.4',
-        'inventories' =>  ['t3coreapi' => 'https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/'],
-    ];

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

@@ -40,4 +40,15 @@
 
         <xsd:attribute name="extends" type="xsd:string"/>
     </xsd:complexType>
+
+    <xsd:complexType name="inventories">
+        <xsd:sequence>
+            <xsd:element name="inventory" type="inventory" minOccurs="1" maxOccurs="unbounded"/>
+        </xsd:sequence>
+    </xsd:complexType>
+
+    <xsd:complexType name="inventory">
+        <xsd:attribute name="name" type="xsd:string" use="required"/>
+        <xsd:attribute name="path" type="xsd:string" use="required"/>
+    </xsd:complexType>
 </xsd:schema>

packages/guides-cli/src/Command/Run.php

@@ -18,7 +18,6 @@
 use phpDocumentor\Guides\Handlers\RenderCommand;
 use phpDocumentor\Guides\Intersphinx\InventoryRepository;
 use phpDocumentor\Guides\Nodes\ProjectNode;
-use phpDocumentor\Guides\Settings\ProjectSettings;
 use phpDocumentor\Guides\Settings\SettingsManager;
 use phpDocumentor\Guides\Twig\Theme\ThemeManager;
 use RuntimeException;
@@ -34,10 +33,8 @@
 use function count;
 use function getcwd;
 use function implode;
-use function is_array;
 use function is_countable;
 use function is_dir;
-use function is_file;
 use function realpath;
 use function sprintf;
 use function str_starts_with;
@@ -120,17 +117,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 'Run "vendor/bin/guides -h" for information on how to configure this command.', $inputDir));
         }
 
-        if (is_file($inputDir . '/settings.php')) {
-            $settingsArray = require $inputDir . '/settings.php';
-            if (!is_array($settingsArray)) {
-                throw new RuntimeException('settings.php must return an array!');
-            }
-
-            $settings = new ProjectSettings($settingsArray);
-            $this->settingsManager->setProjectSettings($settings);
-        } else {
-            $settings = $this->settingsManager->getProjectSettings();
-        }
+        $settings = $this->settingsManager->getProjectSettings();
 
         $projectNode = new ProjectNode(
             $settings->getTitle() === '' ? null : $settings->getTitle(),

packages/guides/src/DependencyInjection/GuidesExtension.php

@@ -39,6 +39,18 @@ public function getConfigTreeBuilder(): TreeBuilder
                         ->scalarNode('version')->end()
                     ->end()
                 ->end()
+                ->arrayNode('inventories')
+                    ->children()
+                        ->arrayNode('inventory')
+                            ->arrayPrototype()
+                                ->children()
+                                    ->scalarNode('id')->end()
+                                    ->scalarNode('url')->end()
+                                ->end()
+                            ->end()
+                        ->end()
+                    ->end()
+                ->end()
                 ->scalarNode('html_theme')->end()
                 ->arrayNode('base_template_paths')
                     ->defaultValue([])
@@ -79,13 +91,22 @@ public function load(array $configs, ContainerBuilder $container): void
         $loader->load('command_bus.php');
         $loader->load('guides.php');
 
+        $projectSettings = [];
         if (isset($config['project'])) {
             if (isset($config['project']['version'])) {
                 $config['project']['version'] = (string) $config['project']['version'];
             }
 
+            $projectSettings = $config['project'];
+        }
+
+        if (isset($config['inventories'])) {
+            $projectSettings['inventories'] = $config['inventories']['inventory'];
+        }
+
+        if ($projectSettings) {
             $container->getDefinition(SettingsManager::class)
-                ->addMethodCall('setProjectSettings', [new ProjectSettings($config['project'])]);
+                ->addMethodCall('setProjectSettings', [new ProjectSettings($projectSettings)]);
         }
 
         if (isset($config['html_theme'])) {

packages/guides/src/Intersphinx/InventoryRepository.php

@@ -18,12 +18,12 @@ public function __construct(private readonly InventoryLoader $inventoryLoader)
     {
     }
 
-    /** @param array<string, string> $inventoryConfigs */
+    /** @param array<int, array<string, string>> $inventoryConfigs */
     public function initialize(array $inventoryConfigs): void
     {
         $this->inventories = [];
-        foreach ($inventoryConfigs as $key => $url) {
-            $this->inventories[$key] = new Inventory($url);
+        foreach ($inventoryConfigs as $inventory) {
+            $this->inventories[$inventory['id']] = new Inventory($inventory['url']);
         }
     }
 

tests/Integration/tests/intersphinx-link/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides>
+    <project title="My Project" version="main (development)" />
+    <inventories>
+        <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+        <inventory id="someapi" url="https://docs.typo3.org/m/typo3/reference-someapi/main/en-us/" />
+    </inventories>
+</guides>

tests/Integration/tests/intersphinx-link/input/settings.php

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides>
+    <project title="My Project" version="main (development)" />
+    <inventories>
+        <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+        <inventory id="t3home" url="https://docs.typo3.org/" />
+    </inventories>
+</guides>

tests/Integration/tests/intersphinx-numeric/input/guides.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides>
+    <project title="My Project" version="3.1.4" />
+    <inventories>
+        <inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/" />
+        <inventory id="t3home" url="https://docs.typo3.org/" />
+    </inventories>
+</guides>