Merge "Add simple configuration doc generator"

autoload.php

@@ -541,6 +541,7 @@ $wgAutoloadLocalClasses = [
 	'GanConverter' => __DIR__ . '/includes/language/converters/GanConverter.php',
 	'GenderCache' => __DIR__ . '/includes/cache/GenderCache.php',
 	'GenerateCollationData' => __DIR__ . '/maintenance/language/generateCollationData.php',
+	'GenerateConfigDoc' => __DIR__ . '/maintenance/generateConfigDoc.php',
 	'GenerateConfigSchema' => __DIR__ . '/maintenance/generateConfigSchema.php',
 	'GenerateJsonI18n' => __DIR__ . '/maintenance/generateJsonI18n.php',
 	'GenerateNormalizerDataAr' => __DIR__ . '/maintenance/language/generateNormalizerDataAr.php',

includes/config-schema.yaml

@@ -1281,7 +1281,7 @@ config-schema:
             **Example:**
 
             ```
-            #$wgMimeDetectorCommand = "file -bi"; # use external MIME detector (Linux)
+            #$wgMimeDetectorCommand = "file -bi"; // use external MIME detector (Linux)
             ```
     TrivialMimeDetection:
         default: false
@@ -2701,7 +2701,9 @@ config-schema:
                             'port' => 4827,
                     ],
             ];
-            ``` You can also pass an array of hosts to send purges too. This is useful when
+            ``` 
+            
+            You can also pass an array of hosts to send purges too. This is useful when
             you have several multicast groups or unicast address that should receive a
             given purge.  Multiple hosts support was introduced in MediaWiki 1.22.
 
@@ -3820,7 +3822,7 @@ config-schema:
             Don't change this unless you know what you're doing
 
             Problematic punctuation:
-              -  []}|#    Are needed for link syntax, never enable these
+              -  []}|#     Are needed for link syntax, never enable these
               -  <>        Causes problems with HTML escaping, don't use
               -  %         Enabled by default, minor problems with path to query rewrite rules, see below
               -  +         Enabled by default, but doesn't work with path to query rewrite rules,
@@ -7431,11 +7433,11 @@ config-schema:
 
             ```
             $wgArticleRobotPolicies = [
-              # Underscore, not space!
+              // Underscore, not space!
               'Main_Page' => 'noindex,follow',
-              # "Project", not the actual project name!
+              // "Project", not the actual project name!
               'Project:X' => 'index,follow',
-              # Needs to be "Abc", not "abc" (unless $wgCapitalLinks is false for that namespace)!
+              // Needs to be "Abc", not "abc" (unless $wgCapitalLinks is false for that namespace)!
               'abc' => 'noindex,nofollow'
             ];
             ```

maintenance/generateConfigDoc.php

@@ -0,0 +1,101 @@
+<?php
+
+/**
+ * Convert a JSON abstract schema to a schema file in the given DBMS type
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ * @ingroup Maintenance
+ */
+
+use MediaWiki\Settings\Source\FileSource;
+
+require_once __DIR__ . '/Maintenance.php';
+
+/**
+ * Maintenance script to generate doc/configuration.md from settings-schema.yaml
+ *
+ * @ingroup Maintenance
+ */
+class GenerateConfigDoc extends Maintenance {
+	/** @var string */
+	private const DEFAULT_INPUT_PATH = 'includes/config-schema.yaml';
+
+	/** @var string */
+	private const DEFAULT_OUTPUT_PATH = 'docs/Configuration.md';
+
+	public function __construct() {
+		parent::__construct();
+		$this->addDescription( 'Build Configuration.md file from config-schema.yaml' );
+
+		$this->addOption(
+			'schema',
+			'Path to the config schema file relative to $IP. Default: ' . self::DEFAULT_INPUT_PATH,
+			false,
+			true
+		);
+		$this->addOption(
+			'output',
+			'Path to output relative to $IP. Default: ' . self::DEFAULT_OUTPUT_PATH,
+			false,
+			true
+		);
+	}
+
+	public function execute() {
+		$input = ( new FileSource( $this->getInputPath() ) )->load();
+
+		$result = "<!-- This file is automatically generated using maintenance/generateConfigDoc.php. -->\n";
+		$result .= "<!-- Do not edit this file directly. -->\n";
+		$result .= "<!-- See maintenance/generateConfigDoc.php for instructions. -->\n";
+
+		$result .= "This is a list of configuration variables that can be set in LocalSettings.php.\n\n";
+
+		// Table of contents
+		$result .= "[TOC]\n\n";
+
+		// Details about each config variable
+		foreach ( $input['config-schema'] as $configKey => $configSchema ) {
+			$result .= "\section $configKey\n";
+			if ( array_key_exists( 'description', $configSchema ) ) {
+				$result .= $configSchema['description'];
+			}
+			$result .= "\n\n";
+		}
+
+		file_put_contents( $this->getOutputPath(), $result );
+	}
+
+	private function getInputPath(): string {
+		global $IP;
+		$inputPath = $this->getOption( 'schema', self::DEFAULT_INPUT_PATH );
+		return $IP . DIRECTORY_SEPARATOR . $inputPath;
+	}
+
+	private function getOutputPath(): string {
+		global $IP;
+		$outputPath = $this->getOption( 'output', self::DEFAULT_OUTPUT_PATH );
+		if ( $outputPath === '-' || $outputPath === 'php://stdout' ) {
+			return 'php://stdout';
+		}
+		return $IP . DIRECTORY_SEPARATOR . $outputPath;
+	}
+
+}
+
+$maintClass = GenerateConfigDoc::class;
+require_once RUN_MAINTENANCE_IF_MAIN;

tests/phpunit/structure/SettingsTest.php

@@ -42,10 +42,10 @@ class SettingsTest extends MediaWikiIntegrationTestCase {
 			new ArrayConfigBuilder(),
 			$this->createNoOpMock( PhpIniSink::class )
 		);
-		$result = $settingsBuilder->loadFile( 'includes/config-schema.yaml' )
+		$validationResult = $settingsBuilder->loadFile( 'includes/config-schema.yaml' )
 			->apply()
 			->validate();
-		$this->assertArrayEquals( [], $result->getErrors() );
+		$this->assertArrayEquals( [], $validationResult->getErrors() );
 	}
 
 	/**
@@ -57,19 +57,28 @@ class SettingsTest extends MediaWikiIntegrationTestCase {
 		$this->assertTrue( $result->isGood(), $result->__toString() );
 	}
 
-	public function testConfigSchemaPhpGenerated() {
-		$schemaGenerator = Shell::makeScriptCommand(
-			__DIR__ . '/../../../maintenance/generateConfigSchema.php',
-			[ '--output', 'php://stdout' ]
-		);
+	public function provideConfigGeneration() {
+		yield 'docs/Configuration.md' => [
+			'script' => __DIR__ . '/../../../maintenance/generateConfigDoc.php',
+			'expectedFile' => __DIR__ . '/../../../docs/Configuration.md',
+		];
+		yield 'incl/Configuration.md' => [
+			'script' => __DIR__ . '/../../../maintenance/generateConfigSchema.php',
+			'expectedFile' => __DIR__ . '/../../../includes/config-schema.php',
+		];
+	}
+
+	/**
+	 * @dataProvider provideConfigGeneration
+	 */
+	public function testConfigGeneration( string $script, string $expectedFile ) {
+		$schemaGenerator = Shell::makeScriptCommand( $script, [ '--output', 'php://stdout' ] );
 
 		$result = $schemaGenerator->execute();
-		$this->assertSame( 0, $result->getExitCode(), 'Config doc generation must finish successfully' );
-		$this->assertSame( '', $result->getStderr(), 'Config doc generation must not have errors' );
+		$this->assertSame( 0, $result->getExitCode(), 'Config generation must finish successfully' );
+		$this->assertSame( '', $result->getStderr(), 'Config generation must not have errors' );
 
-		$oldGeneratedSchema = file_get_contents(
-			__DIR__ . '/../../../includes/config-schema.php'
-		);
+		$oldGeneratedSchema = file_get_contents( $expectedFile );
 
 		$this->assertEquals(
 			$oldGeneratedSchema,