minor #6035 Documentation generation split up and add list. (SpacePos…

…sum)

This PR was merged into the master branch.

Discussion
----------

Documentation generation split up and add list.

closes #5270

Commits
-------

9d704a3 Documentation generation split up and add list.

src/Console/Command/DocumentationCommand.php

@@ -14,8 +14,10 @@
 
 namespace PhpCsFixer\Console\Command;
 
-use PhpCsFixer\Documentation\DocumentationGenerator;
-use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\Documentation\DocumentationLocator;
+use PhpCsFixer\Documentation\FixerDocumentGenerator;
+use PhpCsFixer\Documentation\ListDocumentGenerator;
+use PhpCsFixer\Documentation\RuleSetDocumentationGenerator;
 use PhpCsFixer\FixerFactory;
 use PhpCsFixer\RuleSet\RuleSets;
 use Symfony\Component\Console\Command\Command;
@@ -35,46 +37,28 @@ final class DocumentationCommand extends Command
      */
     protected static $defaultName = 'documentation';
 
-    /**
-     * @var DocumentationGenerator
-     */
-    private $generator;
-
-    public function __construct(?string $name = null)
-    {
-        parent::__construct($name);
-
-        $this->generator = new DocumentationGenerator();
-    }
-
     protected function configure(): void
     {
         $this
             ->setAliases(['doc'])
-            ->setDescription('Dumps the documentation of the project into its /doc directory.')
+            ->setDescription('Dumps the documentation of the project into its "/doc" directory.')
         ;
     }
 
     protected function execute(InputInterface $input, OutputInterface $output): int
     {
+        $filesystem = new Filesystem();
+        $locator = new DocumentationLocator();
+
         $fixerFactory = new FixerFactory();
         $fixerFactory->registerBuiltInFixers();
         $fixers = $fixerFactory->getFixers();
 
-        $this->generateFixersDocs($fixers);
-        $this->generateRuleSetsDocs($fixers);
-
-        $output->writeln('Docs updated.');
-
-        return 0;
-    }
+        $setDefinitions = RuleSets::getSetDefinitions();
 
-    /**
-     * @param FixerInterface[] $fixers
-     */
-    private function generateFixersDocs(array $fixers): void
-    {
-        $filesystem = new Filesystem();
+        $fixerDocumentGenerator = new FixerDocumentGenerator($locator);
+        $ruleSetDocumentationGenerator = new RuleSetDocumentationGenerator($locator);
+        $listDocumentGenerator = new ListDocumentGenerator($locator);
 
         // Array of existing fixer docs.
         // We first override existing files, and then we will delete files that are no longer needed.
@@ -83,51 +67,60 @@ private function generateFixersDocs(array $fixers): void
         $docForFixerRelativePaths = [];
 
         foreach ($fixers as $fixer) {
-            $docForFixerRelativePaths[] = $this->generator->getFixerDocumentationFileRelativePath($fixer);
+            $docForFixerRelativePaths[] = $locator->getFixerDocumentationFileRelativePath($fixer);
             $filesystem->dumpFile(
-                $this->generator->getFixerDocumentationFilePath($fixer),
-                $this->generator->generateFixerDocumentation($fixer)
+                $locator->getFixerDocumentationFilePath($fixer),
+                $fixerDocumentGenerator->generateFixerDocumentation($fixer)
             );
         }
 
         /** @var SplFileInfo $file */
         foreach (
             (new Finder())->files()
-                ->in($this->generator->getFixersDocumentationDirectoryPath())
+                ->in($locator->getFixersDocumentationDirectoryPath())
                 ->notPath($docForFixerRelativePaths) as $file
         ) {
             $filesystem->remove($file->getPathname());
         }
 
-        $index = $this->generator->getFixersDocumentationIndexFilePath();
+        // Fixer doc. index
 
-        if (false === @file_put_contents($index, $this->generator->generateFixersDocumentationIndex($fixers))) {
-            throw new \RuntimeException("Failed updating file {$index}.");
-        }
-    }
+        $filesystem->dumpFile(
+            $locator->getFixersDocumentationIndexFilePath(),
+            $fixerDocumentGenerator->generateFixersDocumentationIndex($fixers)
+        );
 
-    /**
-     * @param FixerInterface[] $fixers
-     */
-    private function generateRuleSetsDocs(array $fixers): void
-    {
-        $filesystem = new Filesystem();
+        // RuleSet docs.
 
         /** @var SplFileInfo $file */
-        foreach ((new Finder())->files()->in($this->generator->getRuleSetsDocumentationDirectoryPath()) as $file) {
+        foreach ((new Finder())->files()->in($locator->getRuleSetsDocumentationDirectoryPath()) as $file) {
             $filesystem->remove($file->getPathname());
         }
 
-        $index = $this->generator->getRuleSetsDocumentationIndexFilePath();
         $paths = [];
 
-        foreach (RuleSets::getSetDefinitions() as $name => $definition) {
-            $paths[$name] = $path = $this->generator->getRuleSetsDocumentationFilePath($name);
-            $filesystem->dumpFile($path, $this->generator->generateRuleSetsDocumentation($definition, $fixers));
+        foreach ($setDefinitions as $name => $definition) {
+            $path = $locator->getRuleSetsDocumentationFilePath($name);
+            $paths[$name] = $path;
+            $filesystem->dumpFile($path, $ruleSetDocumentationGenerator->generateRuleSetsDocumentation($definition, $fixers));
         }
 
-        if (false === @file_put_contents($index, $this->generator->generateRuleSetsDocumentationIndex($paths))) {
-            throw new \RuntimeException("Failed updating file {$index}.");
-        }
+        // RuleSet doc. index
+
+        $filesystem->dumpFile(
+            $locator->getRuleSetsDocumentationIndexFilePath(),
+            $ruleSetDocumentationGenerator->generateRuleSetsDocumentationIndex($paths)
+        );
+
+        // List file / Appendix
+
+        $filesystem->dumpFile(
+            $locator->getListingFilePath(),
+            $listDocumentGenerator->generateListingDocumentation($fixers)
+        );
+
+        $output->writeln('Docs updated.');
+
+        return 0;
     }
 }

src/Documentation/DocumentationLocator.php

@@ -0,0 +1,85 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of PHP CS Fixer.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *     Dariusz Rumiński <dariusz.ruminski@gmail.com>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace PhpCsFixer\Documentation;
+
+use PhpCsFixer\Fixer\FixerInterface;
+use PhpCsFixer\Preg;
+use PhpCsFixer\Utils;
+
+/**
+ * @internal
+ */
+final class DocumentationLocator
+{
+    /**
+     * @var string
+     */
+    private $path;
+
+    public function __construct()
+    {
+        $this->path = \dirname(__DIR__, 2).'/doc';
+    }
+
+    public function getFixersDocumentationDirectoryPath(): string
+    {
+        return $this->path.'/rules';
+    }
+
+    public function getFixersDocumentationIndexFilePath(): string
+    {
+        return $this->getFixersDocumentationDirectoryPath().'/index.rst';
+    }
+
+    public function getFixerDocumentationFilePath(FixerInterface $fixer): string
+    {
+        return $this->getFixersDocumentationDirectoryPath().'/'.Preg::replaceCallback(
+            '/^.*\\\\(.+)\\\\(.+)Fixer$/',
+            static function (array $matches): string {
+                return Utils::camelCaseToUnderscore($matches[1]).'/'.Utils::camelCaseToUnderscore($matches[2]);
+            },
+            \get_class($fixer)
+        ).'.rst';
+    }
+
+    public function getFixerDocumentationFileRelativePath(FixerInterface $fixer): string
+    {
+        return Preg::replace(
+            '#^'.preg_quote($this->getFixersDocumentationDirectoryPath(), '#').'/#',
+            '',
+            $this->getFixerDocumentationFilePath($fixer)
+        );
+    }
+
+    public function getRuleSetsDocumentationDirectoryPath(): string
+    {
+        return $this->path.'/ruleSets';
+    }
+
+    public function getRuleSetsDocumentationIndexFilePath(): string
+    {
+        return $this->getRuleSetsDocumentationDirectoryPath().'/index.rst';
+    }
+
+    public function getRuleSetsDocumentationFilePath(string $name): string
+    {
+        return $this->getRuleSetsDocumentationDirectoryPath().'/'.str_replace(':risky', 'Risky', ucfirst(substr($name, 1))).'.rst';
+    }
+
+    public function getListingFilePath(): string
+    {
+        return $this->path.'/list.rst';
+    }
+}