Update GitHub Pages

Author: coisa

docs/running/index.rst

@@ -13,3 +13,4 @@ In this Section
 
    unified-command
    specialized-commands
+   reports

docs/running/reports.rst

@@ -0,0 +1,55 @@
+Test Reports
+============
+
+FastForward DevTools provides a unified mechanism to generate and aggregate multiple types of reports, including API documentation and testing metrics, into a clean and accessible directory structure.
+
+The Reports Command (``reports``)
+---------------------------------
+
+The ``reports`` command is the high-level orchestrator that sequentially runs the documentation and testing suites with coverage enabled. It then generates a central entry point (``index.html``) in your project's ``public/`` directory.
+
+.. code-block:: bash
+
+   composer dev-tools reports
+
+Unified Output Structure
+------------------------
+
+When you run the reports command, the following structure is created in your project root:
+
+.. code-block:: text
+
+   public/
+   ├── index.html        # The main frontpage linking to all reports
+   ├── docs/             # Generated HTML API documentation (phpDocumentor)
+   └── coverage/         # Testing reports (PHPUnit)
+       ├── index.html    # Detailed HTML Code Coverage report
+       ├── testdox.html  # Human-readable Testdox execution report
+       ├── clover.xml    # XML coverage for CI integration
+       └── coverage.php  # Raw PHP coverage data
+
+Code Coverage
+-------------
+
+The Code Coverage report provides a visual representation of which lines of your code are executed by your tests. It helps identify untested areas of the codebase.
+
+- **Location**: ``public/coverage/index.html``
+- **Generation**: Triggered by ``composer dev-tools reports`` or ``composer dev-tools tests --coverage=public/coverage``.
+
+Testdox
+-------
+
+The Testdox report transforms your technical test case names into a human-readable list of behavioral expectations, serving as a form of living documentation for your project's functionality.
+
+- **Location**: ``public/coverage/testdox.html``
+- **Generation**: Automatically included whenever coverage is generated via the ``reports`` or ``tests`` commands.
+
+Live Reports (GitHub Pages)
+---------------------------
+
+For the latest status of the ``main`` branch, you can access the live reports deployed via GitHub Actions:
+
+- **Full Documentation Hub**: `https://php-fast-forward.github.io/dev-tools/ <https://php-fast-forward.github.io/dev-tools/>`_
+- **API Documentation**: `https://php-fast-forward.github.io/dev-tools/docs/ <https://php-fast-forward.github.io/dev-tools/docs/>`_
+- **Code Coverage**: `https://php-fast-forward.github.io/dev-tools/coverage/ <https://php-fast-forward.github.io/dev-tools/coverage/>`_
+- **Testdox Report**: `https://php-fast-forward.github.io/dev-tools/coverage/testdox.html <https://php-fast-forward.github.io/dev-tools/coverage/testdox.html>`_

resources/index.php

@@ -21,8 +21,6 @@
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
 
-use function Safe\ob_start;
-use function Safe\ob_get_clean;
 
 /**
  * Coordinates the generation of Fast Forward documentation frontpage and related reports.
@@ -62,7 +60,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
     {
         $output->writeln('<info>Generating frontpage for Fast Forward documentation...</info>');
 
-        $docsPath = $this->getAbsolutePath('public/docs');
+        $docsPath = $this->getAbsolutePath('public');
         $coveragePath = $this->getAbsolutePath('public/coverage');
 
         $output->writeln('<info>Generating API documentation on path: ' . $docsPath . '</info>');
@@ -75,55 +73,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             '--coverage' => $coveragePath,
         ], $output);
 
-        $this->generateFrontpage();
-
         $output->writeln('<info>Frontpage generation completed!</info>');
 
         return self::SUCCESS;
     }
-
-    /**
-     * Generates the compiled documentation frontpage correctly.
-     *
-     * This method MUST collect the configured render template and write it persistently
-     * to the `public/index.html` directory.
-     *
-     * @return void
-     */
-    private function generateFrontpage(): void
-    {
-        $html = $this->renderTemplate(
-            $this->getProjectDescription(),
-            [
-                'Documentation' => './docs/index.html',
-                'Testdox Report' => './coverage/testdox.html',
-                'Test Coverage Report' => './coverage/index.html',
-            ]
-        );
-
-        $this->filesystem->dumpFile($this->getAbsolutePath('public/index.html'), $html);
-    }
-
-    /**
-     * Constructs string variations defining standard components by linking to predefined resources.
-     *
-     * The method MUST extract variables correctly and stream the content safely.
-     * It SHALL strictly return the interpreted string structure.
-     *
-     * @param string $title the main title intended for the index interface
-     * @param array<string, string> $links the associative array representing link titles and their URIs
-     *
-     * @return string the evaluated and parsed HTML content
-     */
-    private function renderTemplate(string $title, array $links): string
-    {
-        ob_start();
-        extract([
-            'title' => $title,
-            'links' => $links,
-        ]);
-        include $this->getConfigFile('resources/index.php');
-
-        return ob_get_clean();
-    }
 }

src/Command/ReportsCommand.php

@@ -66,7 +66,7 @@ protected function getCommandHelp(): string
      * @return void
      */
     #[Test]
-    public function executeWillRunDocsAndTestsCommandAndGenerateFrontpage(): void
+    public function executeWillRunDocsAndTestsCommand(): void
     {
         $docsCommand = $this->prophesize(Command::class);
         $docsCommand->ignoreValidationErrors()
@@ -83,10 +83,6 @@ public function executeWillRunDocsAndTestsCommandAndGenerateFrontpage(): void
         $this->application->find('tests')
             ->willReturn($testsCommand->reveal());
 
-        $this->withConfigFile('resources/index.php', true);
-
-        $this->filesystem->dumpFile(Argument::type('string'), Argument::type('string'))->shouldBeCalledOnce();
-
         self::assertSame(ReportsCommand::SUCCESS, $this->invokeExecute());
     }
 }