From 82b9afef77f94d65c237a2918ebf29718a5e6501 Mon Sep 17 00:00:00 2001
From: "Dylan K. Taylor" <dktapps@pmmp.io>
Date: Fri, 12 Aug 2022 18:00:52 +0100
Subject: [PATCH] Allow generating RST permission summaries, to be used on
 doc.pmmp.io

---
 tools/generate-permission-doc.php | 101 ++++++++++++++++++++++++------
 1 file changed, 83 insertions(+), 18 deletions(-)

diff --git a/tools/generate-permission-doc.php b/tools/generate-permission-doc.php
index 09f9892a1..0eed2ba63 100644
--- a/tools/generate-permission-doc.php
+++ b/tools/generate-permission-doc.php
@@ -42,13 +42,23 @@ use const STDERR;
 
 require dirname(__DIR__) . '/vendor/autoload.php';
 
+if(count($argv) > 2){
+	fwrite(STDERR, "Required arguments: md|rst\n");
+	exit(1);
+}
+$format = $argv[1] ?? "md";
+if($format !== "md" && $format !== "rst"){
+	fwrite(STDERR, "Invalid format, expected either \"md\" or \"rst\"\n");
+	exit(1);
+}
+
 function markdownify(string $name) : string{
 	return str_replace(['.', '`', ' '], ['', '', '-'], strtolower($name));
 }
 DefaultPermissions::registerCorePermissions();
 
 $cwd = Utils::assumeNotFalse(getcwd());
-$output = Path::join($cwd, "core-permissions.md");
+$output = Path::join($cwd, "core-permissions.$format");
 echo "Writing output to $output\n";
 $doc = fopen($output, "wb");
 if($doc === false){
@@ -59,36 +69,91 @@ if($doc === false){
 $permissions = PermissionManager::getInstance()->getPermissions();
 ksort($permissions, SORT_STRING);
 
-fwrite($doc, "# PocketMine-MP Core Permissions\n");
+$title = "PocketMine-MP Core Permissions";
+if($format === "md"){
+	fwrite($doc, "# $title\n");
+}else{
+	fwrite($doc, "$title\n");
+	fwrite($doc, str_repeat("=", strlen($title)) . "\n\n");
+}
+
 fwrite($doc, "Generated from PocketMine-MP " . VersionInfo::VERSION()->getFullVersion() . "\n");
 fwrite($doc, "\n");
-fwrite($doc, "| Name | Description | Implied permissions |\n");
-fwrite($doc, "|:-----|:------------|:-------------------:|\n");
+if($format === "md"){
+	fwrite($doc, "| Name | Description | Implied permissions |\n");
+	fwrite($doc, "|:-----|:------------|:-------------------:|\n");
+}else{
+	fwrite($doc, ".. list-table::\n");
+	fwrite($doc, "   :header-rows: 1\n\n");
+	fwrite($doc, "   * - Name\n");
+	fwrite($doc, "     - Description\n");
+	fwrite($doc, "     - Implied permissions\n");
+	fwrite($doc, "\n");
+}
 foreach($permissions as $permission){
-	$link = count($permission->getChildren()) === 0 ? "N/A" : "[Jump](#" . markdownify("Permissions implied by `" . $permission->getName() . "`") . ")";
-	fwrite($doc, "| `" . $permission->getName() . "` | " . $permission->getDescription() . " | $link |\n");
+	if($format === "md"){
+		$link = count($permission->getChildren()) === 0 ? "N/A" : "[Jump](#" . markdownify("Permissions implied by `" . $permission->getName() . "`") . ")";
+		fwrite($doc, "| `" . $permission->getName() . "` | " . $permission->getDescription() . " | $link |\n");
+	}else{
+		fwrite($doc, "   * - ``" . $permission->getName() . "``\n");
+		fwrite($doc, "     - " . $permission->getDescription() . "\n");
+		if(count($permission->getChildren()) === 0){
+			fwrite($doc, "     - N/A\n");
+		}else{
+			fwrite($doc, "     - :ref:`Jump<permissions_implied_by_" . $permission->getName() . ">`\n");
+		}
+	}
 }
 
 fwrite($doc, "\n\n");
-fwrite($doc, "## Implied permissions\n");
-fwrite($doc, "Some permissions automatically grant (or deny) other permissions by default when granted. These are referred to as **implied permissions**.<br>\n");
-fwrite($doc, "Permissions may imply permissions which in turn imply other permissions (e.g. `pocketmine.group.operator` implies `pocketmine.group.user`, which in turn implies `pocketmine.command.help`).<br>\n");
-fwrite($doc, "Implied permissions can be overridden by explicit permissions from elsewhere.<br>\n");
-fwrite($doc, "**Note:** When explicitly denied, implied permissions are inverted. This means that \"granted\" becomes \"denied\" and vice versa.\n");
+
+$title = "Implied permissions";
+if($format === "md"){
+	fwrite($doc, "## $title\n");
+}else{
+	fwrite($doc, "$title\n");
+	fwrite($doc, str_repeat("-", strlen($title)) . "\n\n");
+}
+$newline = $format === "md" ? "<br>\n" : "\n\n";
+$code = $format === "md" ? "`" : "``";
+fwrite($doc, "Some permissions automatically grant (or deny) other permissions by default when granted. These are referred to as **implied permissions**.$newline");
+fwrite($doc, "Permissions may imply permissions which in turn imply other permissions (e.g. {$code}pocketmine.group.operator{$code} implies {$code}pocketmine.group.user{$code}, which in turn implies {$code}pocketmine.command.help{$code}).$newline");
+fwrite($doc, "Implied permissions can be overridden by explicit permissions from elsewhere.$newline");
+fwrite($doc, "**Note:** When explicitly denied, implied permissions are inverted. This means that \"granted\" becomes \"denied\" and vice versa.$newline");
 fwrite($doc, "\n\n");
 foreach($permissions as $permission){
 	if(count($permission->getChildren()) === 0){
 		continue;
 	}
-	fwrite($doc, "### Permissions implied by `" . $permission->getName() . "`\n");
+	$title = "Permissions implied by " . $code . $permission->getName() . $code;
+	if($format === "md"){
+		fwrite($doc, "### $title\n");
+	}else{
+		fwrite($doc, ".. _permissions_implied_by_" . $permission->getName() . ":\n\n");
+		fwrite($doc, "$title\n");
+		fwrite($doc, str_repeat("~", strlen($title)) . "\n\n");
+	}
 	fwrite($doc, "Users granted this permission will also be granted/denied the following permissions implicitly:\n\n");
 
-	fwrite($doc, "| Name | Type |\n");
-	fwrite($doc, "|:-----|:----:|\n");
-	$children = $permission->getChildren();
-	ksort($children, SORT_STRING);
-	foreach(Utils::stringifyKeys($children) as $childName => $isGranted){
-		fwrite($doc, "| `$childName` | " . ($isGranted ? "Granted" : "Denied") . " |\n");
+	if($format === "md"){
+		fwrite($doc, "| Name | Type |\n");
+		fwrite($doc, "|:-----|:----:|\n");
+		$children = $permission->getChildren();
+		ksort($children, SORT_STRING);
+		foreach(Utils::stringifyKeys($children) as $childName => $isGranted){
+			fwrite($doc, "| `$childName` | " . ($isGranted ? "Granted" : "Denied") . " |\n");
+		}
+	}else{
+		fwrite($doc, ".. list-table::\n");
+		fwrite($doc, "   :header-rows: 1\n\n");
+		fwrite($doc, "   * - Name\n");
+		fwrite($doc, "     - Type\n");
+		$children = $permission->getChildren();
+		ksort($children, SORT_STRING);
+		foreach(Utils::stringifyKeys($children) as $childName => $isGranted){
+			fwrite($doc, "   * - ``$childName``\n");
+			fwrite($doc, "     - " . ($isGranted ? "Granted" : "Denied") . "\n");
+		}
 	}
 	fwrite($doc, "\n");
 }