docs(configs): Generate settings.md from ConfigLexicon

.github/workflows/occ-command-documentation.yml

@@ -90,4 +90,4 @@ jobs:
         run: |
           ./occ talk:developer:update-docs
           cd apps/${{ env.APP_NAME }}
-          bash -c "[[ ! \"`git status --porcelain `\" ]] || (cat docs/occ.md && echo 'Documentation outdated. Run the command talk:developer:update-docs locally, commit the occ.md file and push the changes.' && exit 1)"
+          bash -c "[[ ! \"`git status --porcelain `\" ]] || (git diff && echo 'Documentation outdated. Run the command talk:developer:update-docs locally, commit the occ.md and settings.md files and push the changes.' && exit 1)"

lib/Command/Developer/UpdateDocs.php

@@ -9,7 +9,12 @@
 namespace OCA\Talk\Command\Developer;
 
 use OC\Core\Command\Base;
+use OCA\Talk\Config\AppConfigEntry;
+use OCA\Talk\ConfigLexicon;
 use OCP\App\IAppManager;
+use OCP\Config\Lexicon\Entry;
+use OCP\Config\Lexicon\Preset;
+use OCP\Config\ValueType;
 use OCP\Console\Attribute\AsCommand;
 use OCP\IConfig;
 use OCP\Server;
@@ -23,6 +28,7 @@ class UpdateDocs extends Base {
 	public function __construct(
 		private readonly IConfig $config,
 		private readonly IAppManager $appManager,
+		private readonly ConfigLexicon $configLexicon,
 	) {
 		parent::__construct();
 	}
@@ -35,7 +41,7 @@ public function isEnabled(): bool {
 	protected function configure(): void {
 		$this
 			->setName('talk:developer:update-docs')
-			->setDescription('Update documentation of commands')
+			->setDescription('Update documentation of commands and app configs')
 		;
 	}
 
@@ -55,9 +61,73 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 		$handle = fopen(__DIR__ . '/../../../docs/occ.md', 'w');
 		fwrite($handle, $documentation);
 		fclose($handle);
+
+		$settingsFile = __DIR__ . '/../../../docs/settings.md';
+		file_put_contents($settingsFile, $this->replaceAppConfigTable((string)file_get_contents($settingsFile)));
 		return 0;
 	}
 
+	public function replaceAppConfigTable(string $settings): string {
+		$section = strpos($settings, '## App configuration');
+		$start = strpos($settings, "\n| Key ", $section ?: 0);
+		$end = strpos($settings, "\n## ", $start ?: 0);
+		if ($section === false || $start === false || $end === false) {
+			throw new \RuntimeException('Could not find the app configuration table in docs/settings.md');
+		}
+
+		return substr($settings, 0, $start + 1) . $this->getAppConfigTable() . substr($settings, $end);
+	}
+
+	protected function getAppConfigTable(): string {
+		$table = "| Key | Type | Default | Hash | Option | Description |\n";
+		$table .= "|---|---|---|---|---|---|\n";
+		$configs = $this->configLexicon->getTalkAppConfigs();
+		usort($configs, static fn (AppConfigEntry $a, AppConfigEntry $b): int => strcmp($a->entry->getKey(), $b->entry->getKey()));
+		foreach ($configs as $config) {
+			$table .= $this->getAppConfigRow($config) . "\n";
+		}
+		return $table;
+	}
+
+	public function getAppConfigRow(AppConfigEntry $config): string {
+		$entry = $config->entry;
+		return '| `' . $entry->getKey() . '` | '
+			. $this->formatType($config) . ' | '
+			. $this->formatDefault($entry) . ' | '
+			. ($config->hash ? 'Yes' : 'No') . ' | '
+			. ($config->adminSetting ? '🖌️' : '') . ($config->occCommands !== [] ? '💻' : '') . ' | '
+			. ($entry->isDeprecated() ? 'Deprecated: ' : '') . str_replace([PHP_EOL, '|'], ['<br>', '\|'], $entry->getDefinition()) . ' |';
+	}
+
+	protected function formatType(AppConfigEntry $config): string {
+		if ($config->arrayType !== null) {
+			return '`' . str_replace('|', '\|', $config->arrayType) . '`';
+		}
+
+		$type = strtolower($config->entry->getValueType()->name);
+		if ($config->enumType === null) {
+			return $type;
+		}
+
+		$values = array_map(static fn (string $value): string => '`' . $value . '`', explode('|', $config->enumType));
+		$last = array_pop($values);
+		return $type . '<br>' . ($values === [] ? $last : implode(', ', $values) . ' or ' . $last);
+	}
+
+	protected function formatDefault(Entry $entry): string {
+		$default = $entry->getDefault(Preset::NONE);
+		if ($default === null) {
+			return '';
+		}
+		if (str_contains($default, "\n")) {
+			return 'See `lib/ConfigLexicon.php`';
+		}
+		if ($entry->getValueType() === ValueType::BOOL) {
+			return \in_array($default, ['1', 'yes', 'true', 'on'], true) ? '`true`' : '`false`';
+		}
+		return '`' . ($default === '' ? "''" : str_replace('|', '\|', $default)) . '`';
+	}
+
 	protected function getCommand(string $namespace): Command {
 		$asCommand = (new \ReflectionClass($namespace))->getAttributes(AsCommand::class);
 		if ($asCommand !== []) {

lib/Config/AppConfigEntry.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Talk\Config;
+
+use OCP\Config\Lexicon\Entry;
+use OCP\Config\ValueType;
+
+/**
+ * Lexicon entry with the Talk specific details used for the X-Nextcloud-Talk-Hash and the documentation
+ */
+class AppConfigEntry {
+	/**
+	 * @param bool $hash Changing the value changes the X-Nextcloud-Talk-Hash so clients refresh the capabilities
+	 * @param bool $adminSetting The value can be set in the admin settings UI
+	 * @param list<class-string> $occCommands Dedicated occ commands to set the value
+	 * @param ?string $arrayType Psalm style type of the content for {@see ValueType::ARRAY} entries, e.g. `list<string>`
+	 * @param ?string $enumType Allowed values of {@see ValueType::STRING} and {@see ValueType::INT} entries separated by `|`, e.g. `split|unified`
+	 */
+	public function __construct(
+		public readonly Entry $entry,
+		public readonly bool $hash = false,
+		public readonly bool $adminSetting = false,
+		public readonly array $occCommands = [],
+		public readonly ?string $arrayType = null,
+		public readonly ?string $enumType = null,
+	) {
+	}
+}