Docs usability - write http redirects for all aliases in commands & generators

mkdocs_base.yml

@@ -24,9 +24,6 @@ extra_css:
 plugins:
   - edit_url
   - search
-  - redirects:
-      redirect_maps:
-        'commands/pm_enable.md': 'commands/pm_install.md'
   - git-revision-date-localized:
       exclude:
         - commands/*

src/Commands/core/MkCommands.php

@@ -14,6 +14,7 @@
 use Drush\Drush;
 use Drush\SiteAlias\SiteAliasManagerAwareInterface;
 use Symfony\Component\Console\Application;
+use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Filesystem\Filesystem;
@@ -38,14 +39,14 @@ class MkCommands extends DrushCommands implements SiteAliasManagerAwareInterface
     public function docs(): void
     {
         $dir_root = Drush::bootstrapManager()->getComposerRoot();
+
         $destination = 'commands';
         $destination_path = Path::join($dir_root, 'docs', $destination);
         $this->prepare($destination_path);
-
         $application = Drush::getApplication();
         $all = $application->all();
         $namespaced = ListCommands::categorize($all);
-        [$nav_commands, $pages_commands] = $this->writeContentFilesAndAddToNav($namespaced, $destination, $dir_root, $destination_path);
+        [$nav_commands, $pages_commands, $map_commands] = $this->writeContentFilesAndBuildNavAndBuildRedirectMap($namespaced, $destination, $dir_root, $destination_path);
         $this->writeAllMd($pages_commands, $destination_path, 'All commands');
 
         $destination = 'generators';
@@ -56,10 +57,10 @@ public function docs(): void
         $application_generate = $factory->create();
         $all = $this->createAnnotatedCommands($application_generate, Drush::getApplication());
         $namespaced = ListCommands::categorize($all);
-        [$nav_generators, $pages_generators] = $this->writeContentFilesAndAddToNav($namespaced, $destination, $dir_root, $destination_path);
+        [$nav_generators, $pages_generators, $map_generators] = $this->writeContentFilesAndBuildNavAndBuildRedirectMap($namespaced, $destination, $dir_root, $destination_path);
         $this->writeAllMd($pages_generators, $destination_path, 'All generators');
 
-        $this->writeYml($nav_commands, $nav_generators, $dir_root);
+        $this->writeYml($nav_commands, $nav_generators, $map_commands, $map_generators, $dir_root);
     }
 
     public function createAnnotatedCommands(Application $application_generate, Application $application_drush): array
@@ -211,11 +212,12 @@ protected static function appendPreamble($command, $root): string
         return $body;
     }
 
-    protected function writeYml(array $nav_commands, $nav_generators, string $dest): void
+    protected function writeYml(array $nav_commands, array $nav_generators, array $map_commands, array $map_generators, string $dest): void
     {
         $base = Yaml::parseFile(Path::join($dest, 'mkdocs_base.yml'));
         $base['nav'][] = ['Commands' => $nav_commands];
         $base['nav'][] = ['Generators' => $nav_generators];
+        $base['plugins'][]['redirects']['redirect_maps'] = $map_commands + $map_generators;
         $yaml_nav = Yaml::dump($base, PHP_INT_MAX, 2);
 
         // Remove invalid quotes that Symfony YAML adds/needs. https://github.com/symfony/symfony/blob/6.1/src/Symfony/Component/Yaml/Inline.php#L624
@@ -298,28 +300,18 @@ public static function optionToArray(InputOption $opt): iterable
 
     /**
      * Convert text like <info>foo</info> to *foo*.
-     *
-     * @param $text
-     *
-     * @return string
      */
     public static function cliTextToMarkdown(string $text): string
     {
         return str_replace(['<info>', '</info>'], '*', $text);
     }
 
     /**
-     * @param array $namespaced
-     * @param string $destination
-     * @param string $dir_root
-     * @param string $destination_path
-     *
-     * @return array
+     * Write content files, add to nav, build a redirect map.
      */
-    public function writeContentFilesAndAddToNav(array $namespaced, string $destination, string $dir_root, string $destination_path): array
+    public function writeContentFilesAndBuildNavAndBuildRedirectMap(array $namespaced, string $destination, string $dir_root, string $destination_path): array
     {
-        // Write content files and add to nav.
-        $pages = $pages_all = $nav = [];
+        $pages = $pages_all = $nav = $map_all = [];
         foreach ($namespaced as $category => $commands) {
             foreach ($commands as $command) {
                 // Special case a single page
@@ -343,15 +335,41 @@ public function writeContentFilesAndAddToNav(array $namespaced, string $destinat
                 if ($destination == 'commands') {
                     $body .= self::appendPostAmble();
                 }
-                $filename = str_replace(':', '_', $command->getName()) . '.md';
+                $filename = $this->getFilename($command->getName());
                 $pages[$command->getName()] = $destination . "/$filename";
                 file_put_contents(Path::join($destination_path, $filename), $body);
+
+                if ($map = $this->getRedirectMap($command, $destination)) {
+                    $map_all = array_merge($map_all, $map);
+                }
+                unset($map);
             }
             $this->logger()->info('Found {pages} pages in {cat}', ['pages' => count($pages), 'cat' => $category]);
             $nav[] = [$category => $pages];
             $pages_all = array_merge($pages_all, $pages);
             unset($pages);
         }
-        return [$nav, $pages_all];
+        return [$nav, $pages_all, $map_all];
+    }
+
+    protected function getRedirectMap(Command $command, string $destination): array
+    {
+        $map = [];
+        foreach ($command->getAliases() as $alias) {
+            // Skip trivial aliases that differ by a dash.
+            if (str_replace([':', '-'], '', $command->getName()) == str_replace([':', '-'], '', $alias)) {
+                continue;
+            }
+            $map[Path::join($destination, $this->getFilename($alias))] = Path::join($destination, $this->getFilename($command->getName()));
+        }
+        return $map;
+    }
+
+    /**
+     * Get a filename from a command.
+     */
+    public function getFilename(string $name): string
+    {
+        return str_replace(':', '_', $name) . '.md';
     }
 }