Adding the ability to exclude paths through a docs.json file

Depends on doctrine/rst-parser#122

Author: weaverryan

src/BuildContext.php

@@ -10,6 +10,7 @@
 namespace SymfonyDocsBuilder;
 
 use Doctrine\RST\Configuration;
+use Symfony\Component\Finder\Finder;
 
 class BuildContext
 {
@@ -25,6 +26,8 @@ class BuildContext
     private $disableCache = false;
     private $theme;
     private $cacheDirectory;
+    private $excludedPaths = [];
+    private $fileFinder;
 
     public function __construct(
         string $symfonyVersion,
@@ -121,6 +124,32 @@ public function setCacheDirectory(string $cacheDirectory)
         $this->cacheDirectory = $cacheDirectory;
     }
 
+    public function setExcludedPaths(array $excludedPaths)
+    {
+        if (null !== $this->fileFinder) {
+            throw new \LogicException('setExcludePaths() cannot be called after getFileFinder() (because the Finder has been initialized).');
+        }
+
+        $this->excludedPaths = $excludedPaths;
+    }
+
+    public function createFileFinder(): Finder
+    {
+        if (null === $this->fileFinder) {
+            $this->fileFinder = new Finder();
+            $this->fileFinder
+                ->in($this->getSourceDir())
+                // TODO - read this from the rst-parser Configuration
+                ->name('*.rst')
+                ->notName('*.rst.inc')
+                ->files()
+                ->exclude($this->excludedPaths);
+        }
+
+        // clone to get a fresh instance and not share state
+        return clone $this->fileFinder;
+    }
+
     private function checkThatRuntimeConfigIsInitialized()
     {
         if (false === $this->runtimeInitialized) {

src/CI/MissingFilesChecker.php

@@ -17,28 +17,22 @@
 
 class MissingFilesChecker
 {
-    private $finder;
     private $filesystem;
     private $buildContext;
 
     public function __construct(BuildContext $buildContext)
     {
-        $this->finder = new Finder();
         $this->filesystem = new Filesystem();
         $this->buildContext = $buildContext;
     }
 
     public function getMissingFiles(): array
     {
-        $this->finder->in($this->buildContext->getSourceDir())
-            ->exclude(['_build', '.github', '.platform', '_images'])
-            ->notName('*.rst.inc')
-            ->files()
-            ->name('*.rst');
+        $finder = $this->buildContext->createFileFinder();
 
         $orphanedFiles = [];
 
-        foreach ($this->finder as $file) {
+        foreach ($finder as $file) {
             $sourcePath = ltrim(substr($file->getPathname(), \strlen($this->buildContext->getSourceDir())), '/');
 
             $htmlFile = sprintf(

src/Command/BuildDocsCommand.php

@@ -24,6 +24,7 @@
 use Symfony\Component\Filesystem\Filesystem;
 use SymfonyDocsBuilder\BuildContext;
 use SymfonyDocsBuilder\CI\MissingFilesChecker;
+use SymfonyDocsBuilder\ConfigFileParser;
 use SymfonyDocsBuilder\Generator\HtmlForPdfGenerator;
 use SymfonyDocsBuilder\Generator\JsonGenerator;
 use SymfonyDocsBuilder\KernelFactory;
@@ -120,6 +121,9 @@ protected function initialize(InputInterface $input, OutputInterface $output)
             $input->getOption('disable-cache'),
             $input->getOption('no-theme') ? Configuration::THEME_DEFAULT : 'rtd'
         );
+
+        $configFileParser = new ConfigFileParser($this->buildContext, $output);
+        $configFileParser->processConfigFile($sourceDir);
     }
 
     protected function execute(InputInterface $input, OutputInterface $output)

src/ConfigFileParser.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace SymfonyDocsBuilder;
+
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * Parses the docs.json config file
+ */
+class ConfigFileParser
+{
+    private $buildContext;
+    private $output;
+
+    public function __construct(BuildContext $buildContext, OutputInterface $output)
+    {
+        $this->buildContext = $buildContext;
+        $this->output = $output;
+    }
+
+    public function processConfigFile(string $sourceDir): void
+    {
+        $configPath = $sourceDir.'/docs.json';
+        if (!file_exists($configPath)) {
+            $this->output->writeln(sprintf('No config file present at <info>%s</info>', $configPath));
+
+            return;
+        }
+
+        $this->output->writeln(sprintf('Loading config file: <info>%s</info>', $configPath));
+        $configData = json_decode(file_get_contents($configPath), true);
+
+        $exclude = $configData['exclude'] ?? [];
+        $this->buildContext->setExcludedPaths($exclude);
+        unset($configData['exclude']);
+
+        if (count($configData) > 0) {
+            throw new \Exception(sprintf('Unsupported keys in docs.json: %s', implode(', ', array_keys($configData))));
+        }
+    }
+}

src/DocsKernel.php

@@ -36,6 +36,8 @@ public function initBuilder(Builder $builder): void
             $builder->getConfiguration()->getEventManager(),
             $builder->getErrorManager()
         );
+
+        $builder->setScannerFinder($this->buildContext->createFileFinder());
     }
 
     private function initializeListeners(EventManager $eventManager, ErrorManager $errorManager)