Fix documentation generation and contents

.gitignore

@@ -2,5 +2,5 @@
 build/
 composer.phar
 composer.lock
-docs/json/**/*.json
+docs/json/*
 vendor/

dev/src/DocGenerator/Command/Docs.php

@@ -39,6 +39,7 @@ class Docs extends Command
     const DEFAULT_OUTPUT_DIR = 'docs/json';
     const TOC_SOURCE_DIR = 'docs/contents';
     const TOC_TEMPLATE = 'docs/toc.json';
+    const OVERVIEW_FILE = 'docs/overview.html';
     const DEFAULT_SOURCE_DIR = 'src';
 
     private $cliBasePath;
@@ -74,7 +75,8 @@ protected function execute(InputInterface $input, OutputInterface $output)
             'project' => $this->cliBasePath .'/../',
             'manifest' => $this->cliBasePath .'/../docs/manifest.json',
             'toc' => $this->cliBasePath .'/../'. self::TOC_SOURCE_DIR,
-            'tocTemplate' => $this->cliBasePath .'/../'. self::TOC_TEMPLATE
+            'tocTemplate' => $this->cliBasePath .'/../'. self::TOC_TEMPLATE,
+            'overview' => $this->cliBasePath .'/../'. self::OVERVIEW_FILE
         ];
 
         $components = $this->getComponents($paths['source']);
@@ -83,15 +85,33 @@ protected function execute(InputInterface $input, OutputInterface $output)
         foreach ($components as $component) {
             $input = $paths['project'] . $component['path'];
             $source = $this->getFilesList($input);
-            $this->generateComponentDocumentation($output, $source, $component, $paths, $tocTemplate, $release, $pretty);
+            $this->generateComponentDocumentation(
+                $output,
+                $source,
+                $component,
+                $paths,
+                $tocTemplate,
+                $release,
+                $pretty
+            );
         }
 
-        $source = [$paths['project'] .'src/ServiceBuilder.php'];
+        $source = $this->getFilesList($paths['project'] . '/src');
         $component = [
             'id' => 'google-cloud',
             'path' => 'src/'
         ];
-        $this->generateComponentDocumentation($output, $source, $component, $paths, $tocTemplate, $release, $pretty);
+
+        $this->generateComponentDocumentation(
+            $output,
+            $source,
+            $component,
+            $paths,
+            $tocTemplate,
+            $release,
+            $pretty,
+            false
+        );
     }
 
     private function generateComponentDocumentation(
@@ -101,7 +121,8 @@ private function generateComponentDocumentation(
         array $paths,
         $tocTemplate,
         $release = false,
-        $pretty = false
+        $pretty = false,
+        $linkCrossComponent = true
     ) {
         $output->writeln(sprintf('Writing documentation for %s', $component['id']));
         $output->writeln('--------------');
@@ -123,23 +144,29 @@ private function generateComponentDocumentation(
             $this->cliBasePath,
             $component['id'],
             $paths['manifest'],
-            $release
+            $release,
+            $linkCrossComponent
         );
+
         $docs->generate($component['path'], $pretty);
 
         $types->write($pretty);
 
         $output->writeln(sprintf('Writing table of contents to %s', realpath($outputPath)));
-        $services = json_decode(file_get_contents($paths['toc'] .'/'. $component['id'] .'.json'), true);
+        $contents = json_decode(file_get_contents($paths['toc'] .'/'. $component['id'] .'.json'), true);
 
         $toc = new TableOfContents(
             $tocTemplate,
-            $services,
+            $component['id'],
             $release,
+            $paths['toc'],
             $outputPath
         );
         $toc->generate($pretty);
 
+        $output->writeln(sprintf('Copying overview.html to %s', realpath($outputPath)));
+        copy($paths['overview'], $outputPath .'/overview.html');
+
         $output->writeln(' ');
         $output->writeln(' ');
     }

dev/src/DocGenerator/DocGenerator.php

@@ -35,6 +35,7 @@ class DocGenerator
     private $componentId;
     private $manifestPath;
     private $release;
+    private $linkCrossComponent;
 
     /**
      * @param array $files
@@ -46,7 +47,8 @@ public function __construct(
         $executionPath,
         $componentId,
         $manifestPath,
-        $release
+        $release,
+        $linkCrossComponent = true
     ) {
         $this->types = $types;
         $this->files = $files;
@@ -55,6 +57,7 @@ public function __construct(
         $this->componentId = $componentId;
         $this->manifestPath = $manifestPath;
         $this->release = $release;
+        $this->linkCrossComponent = $linkCrossComponent;
     }
 
     /**
@@ -84,7 +87,8 @@ public function generate($basePath, $pretty)
                     dirname($this->executionPath),
                     $this->componentId,
                     $this->manifestPath,
-                    $this->release
+                    $this->release,
+                    $this->linkCrossComponent
                 );
             } else {
                 $content = file_get_contents($file);
@@ -100,7 +104,9 @@ public function generate($basePath, $pretty)
             $this->types->addType([
                 'id' => $document['id'],
                 'title' => $document['title'],
-                'contents' => $this->prune($document['id'] . '.json')
+                'contents' => ($this->linkCrossComponent)
+                    ? $this->prune($document['id'] . '.json')
+                    : $document['id'] . '.json'
             ]);
         }
     }

dev/src/DocGenerator/Parser/CodeParser.php

@@ -39,6 +39,7 @@ class CodeParser implements ParserInterface
     private $componentId;
     private $manifestPath;
     private $release;
+    private $linkCrossComponent;
 
     public function __construct(
         $path,
@@ -47,7 +48,8 @@ public function __construct(
         $projectRoot,
         $componentId,
         $manifestPath,
-        $release
+        $release,
+        $linkCrossComponent = true
     ) {
         $this->path = $path;
         $this->outputName = $outputName;
@@ -58,6 +60,7 @@ public function __construct(
         $this->componentId = $componentId;
         $this->manifestPath = $manifestPath;
         $this->release = $release;
+        $this->linkCrossComponent = $linkCrossComponent;
     }
 
     public function parse()
@@ -504,7 +507,7 @@ private function buildExternalType($type)
     private function buildLink($content)
     {
         $componentId = null;
-        if (substr_compare(trim($content, '\\'), 'Google\Cloud', 0, 12) === 0) {
+        if ($this->linkCrossComponent && substr_compare(trim($content, '\\'), 'Google\Cloud', 0, 12) === 0) {
             try {
                 $matches = [];
                 preg_match('/[Generator\<]?(Google\\\Cloud\\\[\w\\\]{0,})[\>]?[\[\]]?/', $content, $matches);

dev/src/DocGenerator/TableOfContents.php

@@ -20,25 +20,61 @@
 class TableOfContents
 {
     private $template;
-    private $component;
+    private $componentId;
     private $componentVersion;
+    private $contentsPath;
     private $outputPath;
 
-    public function __construct(array $template, array $component, $componentVersion, $outputPath)
+    public function __construct(array $template, $componentId, $componentVersion, $contentsPath, $outputPath)
     {
         $this->template = $template;
-        $this->component = $component;
+        $this->componentId = $componentId;
         $this->componentVersion = $componentVersion;
+        $this->contentsPath = $contentsPath;
         $this->outputPath = $outputPath;
     }
 
     public function generate($pretty = false)
     {
-        $toc = $this->template;
-        $toc['services'] = $this->component;
-        $toc['tagName'] = $this->componentVersion;
+        $toc = $this->getToc($this->componentId);
 
-        $writer = new Writer($toc, $this->outputPath, $pretty);
+        $tpl = $this->template;
+        $tpl['services'] = $this->services($toc);
+        $tpl['tagName'] = $this->componentVersion;
+
+        $writer = new Writer($tpl, $this->outputPath, $pretty);
         $writer->write('toc.json');
     }
+
+    private function services(array $toc)
+    {
+        $services = $toc['services'];
+
+        if (isset($toc['includes'])) {
+            foreach ($toc['includes'] as $include) {
+                $toc = $this->getToc($include);
+                $nested = $toc['services'];
+                $firstService = array_shift($nested);
+
+                $service = [
+                    'title' => $toc['title'],
+                    'type' => $firstService['type'],
+                    'nav' => $nested
+                ];
+
+                if (isset($toc['pattern'])) {
+                    $service['patterns'] = [$toc['pattern']];
+                }
+
+                $services[] = $service;
+            }
+        }
+
+        return $services;
+    }
+
+    private function getToc($componentId)
+    {
+        return json_decode(file_get_contents($this->contentsPath .'/'. $componentId .'.json'), true);
+    }
 }

docs/contents/cloud-bigquery.json

@@ -1,31 +1,35 @@
-[{
-    "title": "BigQueryClient",
-    "type": "bigquery/bigqueryclient"
-}, {
-    "title": "Bytes",
-    "type": "bigquery/bytes"
-}, {
-    "title": "Dataset",
-    "type": "bigquery/dataset"
-}, {
-    "title": "Date",
-    "type": "bigquery/date"
-}, {
-    "title": "InsertResponse",
-    "type": "bigquery/insertresponse"
-}, {
-    "title": "Job",
-    "type": "bigquery/job"
-}, {
-    "title": "QueryResults",
-    "type": "bigquery/queryresults"
-}, {
-    "title": "Table",
-    "type": "bigquery/table"
-}, {
-    "title": "Time",
-    "type": "bigquery/time"
-}, {
-    "title": "Timestamp",
-    "type": "bigquery/timestamp"
-}]
+{
+    "title": "BigQuery",
+    "pattern": "bigquery\/\\w{1,}",
+    "services": [{
+        "title": "BigQueryClient",
+        "type": "bigquery/bigqueryclient"
+    }, {
+        "title": "Bytes",
+        "type": "bigquery/bytes"
+    }, {
+        "title": "Dataset",
+        "type": "bigquery/dataset"
+    }, {
+        "title": "Date",
+        "type": "bigquery/date"
+    }, {
+        "title": "InsertResponse",
+        "type": "bigquery/insertresponse"
+    }, {
+        "title": "Job",
+        "type": "bigquery/job"
+    }, {
+        "title": "QueryResults",
+        "type": "bigquery/queryresults"
+    }, {
+        "title": "Table",
+        "type": "bigquery/table"
+    }, {
+        "title": "Time",
+        "type": "bigquery/time"
+    }, {
+        "title": "Timestamp",
+        "type": "bigquery/timestamp"
+    }]
+}

docs/contents/cloud-core.json

@@ -1,30 +1,37 @@
-[{
-    "title": "Overview",
-    "type": "core/readme"
-}, {
-    "title": "IAM",
-    "type": "core/iam/iam",
-    "patterns": [
-      "core/iam/\\w{1,}"
-    ],
-    "nav": [{
-        "title": "PolicyBuilder",
-        "type": "core/iam/policybuilder"
-    }]
-}, {
-    "title": "Upload",
-    "type": "core/upload/abstractuploader",
-    "nav": [{
-        "title": "MultipartUploader",
-        "type": "core/upload/multipartuploader"
+{
+    "title": "Core",
+    "pattern": "core\/\\w{1,}",
+    "services": [{
+        "title": "Overview",
+        "type": "core/readme"
+    }, {
+        "title": "IAM",
+        "type": "core/iam/iam",
+        "patterns": [
+          "core/iam/\\w{1,}"
+        ],
+        "nav": [{
+            "title": "PolicyBuilder",
+            "type": "core/iam/policybuilder"
+        }]
     }, {
-        "title": "ResumableUploader",
-        "type": "core/upload/resumableuploader"
+        "title": "Upload",
+        "type": "core/upload/abstractuploader",
+        "patterns": [
+          "core/upload/\\w{1,}"
+        ],
+        "nav": [{
+            "title": "MultipartUploader",
+            "type": "core/upload/multipartuploader"
+        }, {
+            "title": "ResumableUploader",
+            "type": "core/upload/resumableuploader"
+        }, {
+            "title": "StreamableUploader",
+            "type": "core/upload/streamableuploader"
+        }]
     }, {
-        "title": "StreamableUploader",
-        "type": "core/upload/streamableuploader"
+        "title": "Int64",
+        "type": "core/int64"
     }]
-}, {
-    "title": "Int64",
-    "type": "core/int64"
-}]
+}