use composition over inheritance for SymfonyHTMLFormat

Author: nikophil

_build/composer.lock

@@ -3,7 +3,12 @@
 namespace SymfonyDocs\Command;
 
 use Doctrine\RST\Builder;
-use Doctrine\RST\Configuration;
+use Doctrine\RST\Event\PostBuildRenderEvent;
+use Doctrine\RST\Event\PostNodeRenderEvent;
+use Doctrine\RST\Event\PostParseDocumentEvent;
+use Doctrine\RST\Event\PreBuildParseEvent;
+use Doctrine\RST\Event\PreBuildRenderEvent;
+use Doctrine\RST\Event\PreBuildScanEvent;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Helper\ProgressBar;
 use Symfony\Component\Console\Input\InputInterface;
@@ -12,9 +17,8 @@
 use Symfony\Component\Console\Style\SymfonyStyle;
 use Symfony\Component\Filesystem\Filesystem;
 use Symfony\Component\Finder\Finder;
-use SymfonyDocs\KernelFactory;
-use SymfonyDocs\SymfonyDocConfiguration;
 use SymfonyDocs\JsonGenerator;
+use SymfonyDocs\KernelFactory;
 
 /**
  * Class ParseDoc
@@ -29,16 +33,21 @@ class ParseDoc extends Command
     private $finder;
     /** @var ProgressBar */
     private $progressBar;
+    /** @var Builder */
+    private $builder;
+    /** @var OutputInterface */
+    private $output;
     private $sourceDir;
     private $htmlOutputDir;
     private $jsonOutputDir;
+    private $parsedFiles = [];
 
     public function __construct()
     {
         parent::__construct(self::$defaultName);
 
         $this->filesystem = new Filesystem();
-        $this->finder = new Finder();
+        $this->finder     = new Finder();
     }
 
     protected function configure()
@@ -48,13 +57,13 @@ protected function configure()
         $this
             ->addOption('source-dir', null, InputOption::VALUE_REQUIRED, 'RST files Source directory', __DIR__.'/../../..')
             ->addOption('html-output-dir', null, InputOption::VALUE_REQUIRED, 'HTML files output directory', __DIR__.'/../../html')
-            ->addOption('json-output-dir', null, InputOption::VALUE_REQUIRED, 'JSON files output directory', __DIR__.'/../../json')
-        ;
+            ->addOption('json-output-dir', null, InputOption::VALUE_REQUIRED, 'JSON files output directory', __DIR__.'/../../json');
     }
 
     protected function initialize(InputInterface $input, OutputInterface $output)
     {
         $this->io = new SymfonyStyle($input, $output);
+        $this->output = $output;
 
         $this->sourceDir = $this->getRealAbsolutePath($input->getOption('source-dir'));
         if (!$this->filesystem->exists($this->sourceDir)) {
@@ -70,30 +79,36 @@ protected function initialize(InputInterface $input, OutputInterface $output)
         if ($this->filesystem->exists($this->jsonOutputDir)) {
             $this->filesystem->remove($this->jsonOutputDir);
         }
+
+        $this->builder = new Builder(KernelFactory::createKernel());
+        $eventManager  = $this->builder->getConfiguration()->getEventManager();
+        $eventManager->addEventListener(
+            [PostParseDocumentEvent::POST_PARSE_DOCUMENT],
+            $this
+        );
+        $eventManager->addEventListener(
+            [PreBuildRenderEvent::PRE_BUILD_RENDER],
+            $this
+        );
     }
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $builder = KernelFactory::createKernel();
-
-//        $builder->addHook([$this, 'handleProgressBar']);
-
         $this->finder->in($input->getOption('source-dir'))
             ->exclude(['_build', '.github', '.platform', '_images'])
             ->notName('*.rst.inc')
             ->name('*.rst');
 
-        $this->io->note(sprintf('Start parsing into html %d rst files', $this->finder->count()));
+        $this->io->note(sprintf('Start parsing %d rst files', $this->finder->count()));
         $this->progressBar = new ProgressBar($output, $this->finder->count());
 
-        $builder->build(
+        $this->builder->build(
             $this->sourceDir,
             $this->htmlOutputDir
         );
 
-        $this->progressBar->finish();
         $this->io->newLine(2);
-        $this->io->success('Parse into html complete');
+        $this->io->success('HTML rendering complete!');
 
         foreach ($this->finder as $file) {
             $htmlFile = str_replace([$this->sourceDir, '.rst'], [$this->htmlOutputDir, '.html'], $file->getRealPath());
@@ -104,7 +119,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
 
         $this->io->note('Start transforming doc into json files');
         $this->progressBar = new ProgressBar($output, $this->finder->count());
-        $jsonGenerator = new JsonGenerator($builder->getDocuments()->getAll());
+        $jsonGenerator     = new JsonGenerator($this->builder->getDocuments()->getAll());
         $jsonGenerator->generateJson($this->htmlOutputDir, $this->jsonOutputDir, $this->progressBar);
         $this->io->newLine(2);
         $this->io->success('Parse process complete');
@@ -125,4 +140,27 @@ private function getRealAbsolutePath(string $path): string
             )
         );
     }
+
+    public function postParseDocument(PostParseDocumentEvent $postParseDocumentEvent)
+    {
+        $file = $postParseDocumentEvent->getDocumentNode()->getEnvironment()->getCurrentFileName();
+        if (!\in_array($file, $this->parsedFiles)) {
+            $this->parsedFiles[] = $postParseDocumentEvent->getDocumentNode()->getEnvironment()->getCurrentFileName();
+            $this->progressBar->advance();
+        }
+    }
+
+    public function preBuildRender()
+    {
+        $eventManager  = $this->builder->getConfiguration()->getEventManager();
+        $eventManager->removeEventListener(
+            [PostParseDocumentEvent::POST_PARSE_DOCUMENT],
+            $this
+        );
+
+        $this->progressBar->finish();
+
+        $this->io->newLine(2);
+        $this->io->note('Start rendering in HTML...');
+    }
 }

_build/src/Command/ParseDoc.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace SymfonyDocs\Directive;
+
+use Doctrine\RST\Directives\SubDirective;
+
+class RoleDirective extends SubDirective
+{
+    public function getName() : string
+    {
+        return 'role';
+    }
+}

_build/src/Directive/RoleDirective.php

@@ -4,7 +4,7 @@
 
 use Doctrine\RST\Configuration;
 use Doctrine\RST\Kernel;
-use SymfonyDocs\Directive as SymfonyDoirectives;
+use SymfonyDocs\Directive as SymfonyDirectives;
 use SymfonyDocs\Reference as SymfonyRefernces;
 
 /**
@@ -17,7 +17,12 @@ public static function createKernel(): Kernel
         $configuration = new Configuration();
         $configuration->setCustomTemplateDirs([__DIR__.'/Templates']);
         $configuration->setCacheDir(__DIR__.'/../var/cache');
-        $configuration->addFormat(new SymfonyFormat($configuration->getTemplateRenderer()));
+        $configuration->addFormat(
+            new SymfonyHTMLFormat(
+                $configuration->getTemplateRenderer(),
+                $configuration->getFormat()
+            )
+        );
 
         return new Kernel(
             $configuration,
@@ -29,17 +34,18 @@ public static function createKernel(): Kernel
     private static function getDirectives(): array
     {
         return [
-            new SymfonyDoirectives\CautionDirective(),
-            new SymfonyDoirectives\ClassDirective(),
-            new SymfonyDoirectives\CodeBlockDirective(),
-            new SymfonyDoirectives\ConfigurationBlockDirective(),
-            new SymfonyDoirectives\IndexDirective(),
-            new SymfonyDoirectives\NoteDirective(),
-            new SymfonyDoirectives\SeeAlsoDirective(),
-            new SymfonyDoirectives\SidebarDirective(),
-            new SymfonyDoirectives\TipDirective(),
-            new SymfonyDoirectives\VersionAddedDirective(),
-            new SymfonyDoirectives\BestPracticeDirective(),
+            new SymfonyDirectives\CautionDirective(),
+            new SymfonyDirectives\ClassDirective(),
+            new SymfonyDirectives\CodeBlockDirective(),
+            new SymfonyDirectives\ConfigurationBlockDirective(),
+            new SymfonyDirectives\IndexDirective(),
+            new SymfonyDirectives\RoleDirective(),
+            new SymfonyDirectives\NoteDirective(),
+            new SymfonyDirectives\SeeAlsoDirective(),
+            new SymfonyDirectives\SidebarDirective(),
+            new SymfonyDirectives\TipDirective(),
+            new SymfonyDirectives\VersionAddedDirective(),
+            new SymfonyDirectives\BestPracticeDirective(),
         ];
     }
 

_build/src/KernelFactory.php

@@ -2,6 +2,7 @@
 
 namespace SymfonyDocs;
 
+use Doctrine\RST\Formats\Format;
 use Doctrine\RST\HTML\HTMLFormat;
 use Doctrine\RST\Nodes\CodeNode;
 use Doctrine\RST\Nodes\SpanNode;
@@ -10,25 +11,37 @@
 use Doctrine\RST\Templates\TemplateRenderer;
 
 /**
- * Class SymfonyFormat
+ * Class SymfonyHTMLFormat
  */
-final class SymfonyFormat extends HTMLFormat
+final class SymfonyHTMLFormat implements Format
 {
     /** @var TemplateRenderer */
     protected $templateRenderer;
+    /** @var HTMLFormat */
+    private $htmlFormat;
 
-    public function __construct(TemplateRenderer $templateRenderer)
+    public function __construct(TemplateRenderer $templateRenderer, Format $HTMLFormat)
     {
-        parent::__construct($templateRenderer);
         $this->templateRenderer = $templateRenderer;
+        $this->htmlFormat       = $HTMLFormat;
+    }
+
+    public function getFileExtension(): string
+    {
+        return Format::HTML;
+    }
+
+    public function getDirectives(): array
+    {
+        return $this->htmlFormat->getDirectives();
     }
 
     /**
      * @return NodeRendererFactory[]
      */
     public function getNodeRendererFactories(): array
     {
-        $nodeRendererFactories = parent::getNodeRendererFactories();
+        $nodeRendererFactories = $this->htmlFormat->getNodeRendererFactories();
 
         $nodeRendererFactories[CodeNode::class] = new CallableNodeRendererFactory(
             function (CodeNode $node) {

_build/src/SymfonyFormat.php renamed to _build/src/SymfonyHTMLFormat.php

@@ -70,7 +70,7 @@ Configuration
   * `lifetime`_ (deprecated since 2.8)
   * `matcher`_
 
-    * `ip`_
+    * :ref:`ip <reference-profiler-matcher-ip>`
     * :ref:`path <reference-profiler-matcher-path>`
     * `service`_
 
@@ -680,13 +680,15 @@ matcher
 .......
 
 Matcher options are configured to dynamically enable the profiler. For
-instance, based on the `ip`_ or :ref:`path <reference-profiler-matcher-path>`.
+instance, based on the :ref:`ip <reference-profiler-matcher-ip>` or :ref:`path <reference-profiler-matcher-path>`.
 
 .. seealso::
 
     See :doc:`/profiler/matchers` for more information about using
     matchers to enable/disable the profiler.
 
+.. _reference-profiler-matcher-ip:
+
 ip
 ""