Fix doc generator

googleapis · Mar 5, 2018 · f714d67 · f714d67
1 parent d0768c3
commit f714d67
Show file tree

Hide file tree

Showing 4 changed files with 83 additions and 41 deletions.
diff --git a/dev/src/DocGenerator/Command/Docs.php b/dev/src/DocGenerator/Command/Docs.php
@@ -51,6 +51,8 @@ class Docs extends Command
         'tests/Snippet',
         'tests/System',
         'tests/Conformance',
+        'tests/Perf',
+        'tests/conformance-fixtures'
     ];
 
     public function __construct($cliBasePath)
@@ -67,13 +69,15 @@ protected function configure()
             ->addOption('release', 'r', InputOption::VALUE_NONE, 'If set, docs will be generated into tag folders' .
                 ' such as v1.0.0 rather than master.')
             ->addOption('pretty', 'p', InputOption::VALUE_NONE, 'If set, json files will be written with pretty'.
-                ' formatting using PHP\'s JSON_PRETTY_PRINT flag');
+                ' formatting using PHP\'s JSON_PRETTY_PRINT flag')
+            ->addOption('component', 'c', InputOption::VALUE_OPTIONAL, 'Generate docs only for a single component.');
     }
 
     protected function execute(InputInterface $input, OutputInterface $output)
     {
         $release = $input->getOption('release');
         $pretty = $input->getOption('pretty');
+        $component = $input->getOption('component');
 
         $paths = [
             'source' => $this->cliBasePath .'/../'. self::DEFAULT_SOURCE_DIR,
@@ -88,51 +92,67 @@ protected function execute(InputInterface $input, OutputInterface $output)
         $components = $this->getComponents(dirname($this->cliBasePath), $paths['source']);
         $tocTemplate = json_decode(file_get_contents($paths['tocTemplate']), true);
 
-        foreach ($components as $component) {
-            $input = $paths['project'] . $component['path'] .'/src';
-            $source = $this->getFilesList($input, ['php', 'md'], [
-                'CONTRIBUTING.md'
+        if ($component !== 'google-cloud') {
+            if ($component) {
+                $components = array_filter($components, function ($componentInfo) use ($component) {
+                    return $componentInfo['id'] === $component;
+                });
+
+                if (!$components) {
+                    throw new \RuntimeException(sprintf('Given component ID %s does not exist', $component));
+                }
+            }
+
+            foreach ($components as $component) {
+                $input = $paths['project'] . $component['path'] .'/src';
+                $source = $this->getFilesList($input, ['php', 'md'], [
+                    'CONTRIBUTING.md'
+                ]);
+                $this->generateComponentDocumentation(
+                    $output,
+                    $source,
+                    $component,
+                    $paths,
+                    $tocTemplate,
+                    $release,
+                    $pretty
+                );
+            }
+        }
+
+        if (!$component || $component === 'google-cloud') {
+            $projectRealPath = realpath($paths['project']);
+            $source = $this->getFilesList($projectRealPath, [
+                'php', 'md'
+            ], [
+                '/vendor',
+                '/dev',
+                '/build',
+                '/docs',
+                '/tests',
+                '.github',
+                '/CODE_OF_CONDUCT.md',
+                '/README.md',
+                'bootstrap.php'
             ]);
+
+
+            $component = [
+                'id' => 'google-cloud',
+                'path' => 'src/'
+            ];
+
             $this->generateComponentDocumentation(
                 $output,
                 $source,
                 $component,
                 $paths,
                 $tocTemplate,
                 $release,
-                $pretty
+                $pretty,
+                false
             );
         }
-
-        $projectRealPath = realpath($paths['project']);
-        $source = $this->getFilesList($projectRealPath, [
-            'php', 'md'
-        ], [
-            $projectRealPath .'/vendor',
-            $projectRealPath .'/dev',
-            $projectRealPath .'/build',
-            $projectRealPath .'/docs',
-            $projectRealPath .'/tests',
-            '.github',
-            new RegexFileFilter(str_replace('/', '\/', preg_quote($projectRealPath .'/') . '\w{0,}\.\w{0,}')),
-            'bootstrap.php'
-        ]);
-
-        $component = [
-            'id' => 'google-cloud',
-            'path' => 'src/'
-        ];
-
-        $this->generateComponentDocumentation(
-            $output,
-            $source,
-            $component,
-            $paths,
-            $tocTemplate,
-            $release,
-            $pretty,
-            false
-        );
     }
 
     private function generateComponentDocumentation(
@@ -209,7 +229,13 @@ private function getFilesList($source, array $types, array $excludes = [])
         $directoryIterator = new RecursiveDirectoryIterator($source);
         $iterator = new RecursiveIteratorIterator($directoryIterator);
         // $regexIterator = new RegexIterator($iterator, $regex, RecursiveRegexIterator::GET_MATCH);
-        $fileList = new FileListFilterIterator($iterator, $types, $this->testPaths, $excludes);
+        $fileList = new FileListFilterIterator(
+            realpath($this->cliBasePath .'/../'),
+            $iterator,
+            $types,
+            $this->testPaths,
+            $excludes
+        );
         $files = [];
 
         foreach ($fileList as $item) {

diff --git a/dev/src/DocGenerator/FileListFilterIterator.php b/dev/src/DocGenerator/FileListFilterIterator.php
@@ -22,16 +22,19 @@
  */
 class FileListFilterIterator extends \FilterIterator
 {
+    private $projectRootPath;
     private $fileTypes = [];
     private $testPaths = [];
     private $excludes = [];
 
     public function __construct(
+        $projectRootPath,
         \Iterator $iterator,
         array $fileTypes,
         array $testPaths,
         array $excludes
     ) {
+        $this->projectRootPath = $projectRootPath;
         $this->fileTypes = $fileTypes;
         $this->testPaths = $testPaths;
         $this->excludes = $excludes;
@@ -44,7 +47,7 @@ public function accept()
         /** @var \SplFileInfo */
         $file = parent::current();
 
-        $path = realpath($file->getPathName());
+        $path = '/' . trim(str_replace($this->projectRootPath, '', realpath($file->getPathName())), '/');
 
         if (!in_array($file->getExtension(), $this->fileTypes)) {
             return false;

diff --git a/dev/src/DocGenerator/Parser/CodeParser.php b/dev/src/DocGenerator/Parser/CodeParser.php
@@ -195,7 +195,7 @@ private function buildDocument($fileReflector, $reflector)
         }
 
         if (is_null($docBlock)) {
-            throw new \Exception(sprintf('%s has no description', $fullName));
+            throw new \Exception(sprintf('%s has no description (%s)', $fullName, $fileReflector->getFilename()));
         }
 
         $split = $this->splitDescription($docBlock->getText());

diff --git a/dev/src/DocGenerator/Parser/MarkdownParser.php b/dev/src/DocGenerator/Parser/MarkdownParser.php
@@ -31,18 +31,31 @@ public function __construct($currentFile, $content)
         $this->currentFile = $currentFile;
         $this->content = $content;
         $this->markdown = Parsedown::instance();
+
+        set_error_handler(function($number, $error){
+            if (preg_match('/^DOMDocument::loadHTML\(\): (.+)$/', $error, $m) === 1) {
+                throw new \Exception($m[1]);
+            }
+        });
     }
 
     public function parse()
     {
         $html = $this->markdown->parse($this->content);
 
-        $doc = new DOMDocument;
-        $doc->loadHTML($html);
+        try {
+            $doc = new DOMDocument;
+            $doc->loadHTML($html);
+        } catch (\Exception $e) {
+            throw new \RuntimeException($e->getMessage() .' ('. $this->currentFile .')');
+        }
 
         $headings = $doc->getElementsByTagName('h1');
         $heading = $headings->item(0);
 
+        if (!$heading) {
+            throw new \RuntimeException('Missing h1 tag ('. $this->currentFile .')');
+        }
         $heading->parentNode->removeChild($heading);
 
         $pathinfo = pathinfo($this->currentFile);