Merge pull request #15 from weaverryan/build-system-updates

Various build system updates

Author: weaverryan

_build/src/Command/ParseDoc.php

@@ -8,6 +8,7 @@
 use Doctrine\RST\Event\PreBuildRenderEvent;
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Helper\ProgressBar;
+use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
@@ -54,9 +55,8 @@ protected function configure()
         parent::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')
+            ->addArgument('source-dir', null, InputArgument::REQUIRED, 'RST files Source directory')
+            ->addArgument('output-dir', null, InputArgument::OPTIONAL, 'HTML files output directory')
             ->addOption('parse-only', null, InputOption::VALUE_OPTIONAL, 'Parse only given directory for PDF (directory relative from source-dir)', null);
     }
 
@@ -65,17 +65,18 @@ protected function initialize(InputInterface $input, OutputInterface $output)
         $this->io     = new SymfonyStyle($input, $output);
         $this->output = $output;
 
-        $this->sourceDir = rtrim($this->getRealAbsolutePath($input->getOption('source-dir')), '/');
+        $this->sourceDir = rtrim($this->getRealAbsolutePath($input->getArgument('source-dir')), '/');
         if (!$this->filesystem->exists($this->sourceDir)) {
             throw new \InvalidArgumentException(sprintf('RST source directory "%s" does not exist', $this->sourceDir));
         }
 
-        $this->htmlOutputDir = rtrim($this->getRealAbsolutePath($input->getOption('html-output-dir')), '/');
+        $outputDir = $input->getArgument('output-dir') ?? $this->sourceDir . '/html';
+        $this->htmlOutputDir = rtrim($this->getRealAbsolutePath($outputDir), '/');
         if ($this->filesystem->exists($this->htmlOutputDir)) {
             $this->filesystem->remove($this->htmlOutputDir);
         }
 
-        $this->jsonOutputDir = $this->getRealAbsolutePath($input->getOption('json-output-dir'));
+        $this->jsonOutputDir = $this->getRealAbsolutePath($outputDir.'/json');
         if ($this->filesystem->exists($this->jsonOutputDir)) {
             $this->filesystem->remove($this->jsonOutputDir);
         }
@@ -106,7 +107,7 @@ protected function initialize(InputInterface $input, OutputInterface $output)
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
-        $this->finder->in($input->getOption('source-dir'))
+        $this->finder->in($input->getArgument('source-dir'))
             ->exclude(['_build', '.github', '.platform', '_images'])
             ->notName('*.rst.inc')
             ->name('*.rst');

_build/src/Directive/AbstractAdmonitionDirective.php

@@ -27,6 +27,7 @@ final public function processSub(Parser $parser, ?Node $document, string $variab
             [
                 'name' => $this->name,
                 'text' => $this->text,
+                'class' => null,
             ]
         );
 

_build/src/Directive/AdmonitionDirective.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace SymfonyDocs\Directive;
+
+use Doctrine\RST\Directives\SubDirective;
+use Doctrine\RST\Nodes\Node;
+use Doctrine\RST\Parser;
+
+class AdmonitionDirective extends SubDirective
+{
+    public function processSub(Parser $parser, ?Node $document, string $variable, string $data, array $options): ?Node
+    {
+        $wrapperDiv = $parser->renderTemplate(
+            'directives/admonition.html.twig',
+            [
+                // a bit strange, but on the old markup we literally
+                // had a class of 'admonition-"
+                'name' => '',
+                'text' => $data,
+                'class' => isset($options['class']) ? $options['class'] : null,
+            ]
+        );
+
+        return $parser->getNodeFactory()->createWrapperNode($document, $wrapperDiv, '</div></div>');
+    }
+
+    public function getName(): string
+    {
+        return 'admonition';
+    }
+}

_build/src/KernelFactory.php

@@ -5,14 +5,14 @@
 use Doctrine\RST\Configuration;
 use Doctrine\RST\Kernel;
 use SymfonyDocs\Directive as SymfonyDirectives;
-use SymfonyDocs\Reference as SymfonyRefernces;
+use SymfonyDocs\Reference as SymfonyReferences;
 
 /**
  * Class KernelFactory
  */
 final class KernelFactory
 {
-    public static function createKernel(?string $parseOnly): Kernel
+    public static function createKernel(string $parseOnlyPath = null): Kernel
     {
         $configuration = new Configuration();
         $configuration->setCustomTemplateDirs([__DIR__.'/Templates']);
@@ -24,16 +24,16 @@ public static function createKernel(?string $parseOnly): Kernel
             )
         );
 
-        if ($parseOnly) {
+        if ($parseOnlyPath) {
             $configuration->setBaseUrl(
                 sprintf(
                     SymfonyDocConfiguration::getSymfonyDocUrl(),
                     SymfonyDocConfiguration::getVersion()
                 )
             );
             $configuration->setBaseUrlEnabledCallable(
-                static function (string $path) use ($parseOnly) : bool {
-                    return strpos($path, $parseOnly) !== 0;
+                static function (string $path) use ($parseOnlyPath) : bool {
+                    return strpos($path, $parseOnlyPath) !== 0;
                 }
             );
         }
@@ -48,6 +48,7 @@ static function (string $path) use ($parseOnly) : bool {
     private static function getDirectives(): array
     {
         return [
+            new SymfonyDirectives\AdmonitionDirective(),
             new SymfonyDirectives\CautionDirective(),
             new SymfonyDirectives\ClassDirective(),
             new SymfonyDirectives\CodeBlockDirective(),
@@ -66,14 +67,14 @@ private static function getDirectives(): array
     private static function getReferences(): array
     {
         return [
-            new SymfonyRefernces\DocReference(),
-            new SymfonyRefernces\RefReference(),
-            new SymfonyRefernces\ClassReference(),
-            new SymfonyRefernces\MethodReference(),
-            new SymfonyRefernces\NamespaceReference(),
-            new SymfonyRefernces\PhpFunctionReference(),
-            new SymfonyRefernces\PhpMethodReference(),
-            new SymfonyRefernces\PhpClassReference(),
+            new SymfonyReferences\DocReference(),
+            new SymfonyReferences\RefReference(),
+            new SymfonyReferences\ClassReference(),
+            new SymfonyReferences\MethodReference(),
+            new SymfonyReferences\NamespaceReference(),
+            new SymfonyReferences\PhpFunctionReference(),
+            new SymfonyReferences\PhpMethodReference(),
+            new SymfonyReferences\PhpClassReference(),
         ];
     }
 }

_build/src/Templates/default/html/directives/admonition.html.twig

@@ -1,4 +1,3 @@
-<div class="admonition-{{ name }} admonition-wrapper">
-    <div class="{{ name }}"></div>
+<div class="admonition-wrapper{{ class ? (' '~class) : '' }}">
     <div class="admonition admonition-{{ name }}">
         <p class="admonition-title">{{ text }}</p>

_build/src/Templates/default/html/directives/sidebar.html.twig

@@ -1 +1 @@
-<div class="admonition-wrapper"><div class="sidebar"></div><div class="admonition admonition-sidebar"><p class="sidebar-title">{{ title|raw }}</p>
+<div class="admonition-wrapper"><div class="admonition admonition-sidebar"><p class="sidebar-title">{{ title|raw }}</p>

_build/tests/IntegrationTest.php

@@ -144,6 +144,10 @@ public function parserUnitBlockProvider()
             'blockName' => 'directives/note',
         ];
 
+        yield 'admonition' => [
+            'blockName' => 'directives/admonition',
+        ];
+
         yield 'note-code-block-nested' => [
             'blockName' => 'directives/note-code-block-nested',
         ];

_build/tests/fixtures/expected/blocks/directives/admonition.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8" />
+</head>
+<body>
+<div class="admonition-wrapper screencast_class">
+    <div class="admonition admonition-">
+        <p class="admonition-title">Screencast</p>
+        <p>Do you prefer video tutorials? Check out the the screencasts.</p>
+    </div>
+</div>
+</body>
+</html>

_build/tests/fixtures/expected/blocks/directives/best-practice.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-best-practice admonition-wrapper">
-    <div class="best-practice"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-best-practice">
         <p class="admonition-title">Best Practice</p>
         <p>Use the bcrypt encoder for hashing your users' passwords.</p>

_build/tests/fixtures/expected/blocks/directives/caution.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-caution admonition-wrapper">
-    <div class="caution"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-caution">
         <p class="admonition-title">Caution</p>
         <p>Using too many sidebars or caution directives can be distracting!</p>

_build/tests/fixtures/expected/blocks/directives/note-code-block-nested.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-note admonition-wrapper">
-    <div class="note"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-note">
         <p class="admonition-title">Note</p>
         <p>test</p>

_build/tests/fixtures/expected/blocks/directives/note.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-note admonition-wrapper">
-    <div class="note"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-note">
         <p class="admonition-title">Note</p>
         <p>Sometimes we add notes. But not too often because they interrupt the flow.</p>

_build/tests/fixtures/expected/blocks/directives/seealso.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-seealso admonition-wrapper">
-    <div class="seealso"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-seealso">
         <p class="admonition-title">See also</p>
         <p>Also check out the homepage</p>

_build/tests/fixtures/expected/blocks/directives/sidebar-code-block-nested.html

@@ -5,7 +5,6 @@
 </head>
 <body>
 <div class="admonition-wrapper">
-    <div class="sidebar"></div>
     <div class="admonition admonition-sidebar">
         <p class="sidebar-title">The sidebar's title</p>
         <p>some text before code block</p>

_build/tests/fixtures/expected/blocks/directives/sidebar.html

@@ -5,7 +5,6 @@
 </head>
 <body>
 <div class="admonition-wrapper">
-    <div class="sidebar"></div>
     <div class="admonition admonition-sidebar">
         <p class="sidebar-title">The sidebar's title</p>
         <p>some text inside sidebar</p>

_build/tests/fixtures/expected/blocks/directives/tip.html

@@ -4,8 +4,7 @@
     <meta charset="utf-8" />
 </head>
 <body>
-<div class="admonition-tip admonition-wrapper">
-    <div class="tip"></div>
+<div class="admonition-wrapper">
     <div class="admonition admonition-tip">
         <p class="admonition-title">Tip</p>
         <p>This is a little tip about something! We an also talk about specific</p>

_build/tests/fixtures/source/blocks/directives/admonition.rst

@@ -0,0 +1,4 @@
+.. admonition:: Screencast
+    :class: screencast_class
+
+    Do you prefer video tutorials? Check out the the screencasts.