feat(docs): add product neutral guides (#8077)

* feat(docs): add product neutral guides * remove unused param
googleapis · Feb 7, 2025 · b3927a4 · b3927a4
1 parent bc9ba08
commit b3927a4
Show file tree

Hide file tree

Showing 3 changed files with 106 additions and 25 deletions.
diff --git a/.kokoro/docs/publish.sh b/.kokoro/docs/publish.sh
@@ -60,6 +60,13 @@ $PROJECT_DIR/dev/google-cloud docfx \
     $STAGING_FLAG \
     $VERBOSITY_FLAG
 
+# Add product-neutral guides
+$PROJECT_DIR/dev/google-cloud docfx \
+    --generate-product-neutral-guides \
+    --metadata-version 1.0.0 \
+    $STAGING_FLAG \
+    $VERBOSITY_FLAG
+
 # If this run after a release, store the released artifacts.
 if [ "$KOKORO_GITHUB_COMMIT" != "" ]; then
     # Move to the project directory

diff --git a/dev/src/Command/DocFxCommand.php b/dev/src/Command/DocFxCommand.php
@@ -50,6 +50,12 @@ class DocFxCommand extends Command
             => 'ConfigServiceV2Client::getViewAsync()'
     ];
 
+    private static array $productNeutralGuides = [
+        'AUTHENTICATION.md' => 'Authentication',
+        'DEBUG.md' => 'Debug Logging',
+        'MIGRATING.md' => 'Migrating to V2',
+    ];
+
     protected function configure()
     {
         $this->setName('docfx')
@@ -61,6 +67,7 @@ protected function configure()
             ->addOption('staging-bucket', '', InputOption::VALUE_REQUIRED, 'Upload to the specified staging bucket using docuploader.')
             ->addOption('path', '', InputOption::VALUE_OPTIONAL, 'Specify the path to the composer package to generate.')
             ->addOption('--with-cache', '', InputOption::VALUE_NONE, 'Cache expensive proto namespace lookups to a file')
+            ->addOption('--generate-product-neutral-guides', '', InputOption::VALUE_NONE, 'Instead of a component, generate product-neutral guides.')
         ;
     }
 
@@ -70,12 +77,67 @@ protected function execute(InputInterface $input, OutputInterface $output)
             throw new RuntimeException('This command must be run on PHP 8.0 or above');
         }
 
+        // YAML dump configuration
+        $inline = 11; // The level where you switch to inline YAML
+        $indent = 2; // The amount of spaces to use for indentation of nested nodes
+        $flags = Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK;
+
+        $outDir = $input->getOption('out');
+        if (!is_dir($outDir)) {
+            if (!mkdir($outDir)) {
+                throw new RuntimeException('out directory doesn\'t exist and cannot be created');
+            }
+        }
+
+        if ($input->getOption('generate-product-neutral-guides')) {
+            $output->writeln('Generating <options=bold;fg=white>product neutral guides</>');
+            $tocItems = [];
+            foreach (self::$productNeutralGuides as $file => $name) {
+                file_put_contents(
+                    $outDir . '/' . strtolower($file),
+                    file_get_contents(Component::ROOT_DIR . '/' . $file)
+                );
+                $tocItems[] = ['name' => $name, 'href' => strtolower($file)];
+            }
+            // Write the TOC to a file
+            $guideToc = array_filter([
+                'uid' => 'product-neutral-guides',
+                'name' => 'Client library help',
+                'items' => $tocItems,
+            ]);
+            $tocYaml = Yaml::dump([$guideToc], $inline, $indent, $flags);
+            $outFile = sprintf('%s/toc.yml', $outDir);
+            file_put_contents($outFile, $tocYaml);
+
+            $output->writeln('Done.');
+
+            if ($metadataVersion = $input->getOption('metadata-version')) {
+                $output->write(sprintf('Writing docs.metadata with version <fg=white>%s</>... ', $metadataVersion));
+                $process = new Process([
+                    'docuploader', 'create-metadata',
+                    '--name', 'help',
+                    '--version', $metadataVersion,
+                    '--language', 'php',
+                    $outDir . '/docs.metadata'
+                ]);
+                $process->mustRun();
+                $output->writeln('Done.');
+            }
+
+            if ($stagingBucket = $input->getOption('staging-bucket')) {
+                $output->write(sprintf('Running docuploader to upload to staging bucket <fg=white>%s</>... ', $stagingBucket));
+                $this->uploadToStagingBucket($outDir, $stagingBucket);
+                $output->writeln('Done.');
+            }
+
+            return 0;
+        }
+
         $componentPath = $input->getOption('path');
         $componentName = rtrim($input->getOption('component'), '/') ?: basename($componentPath ?: getcwd());
         $component = new Component($componentName, $componentPath);
         $output->writeln(sprintf('Generating documentation for <options=bold;fg=white>%s</>', $componentName));
         $xml = $input->getOption('xml');
-        $outDir = $input->getOption('out');
         if (empty($xml)) {
             $output->write('Running phpdoc to generate structure.xml... ');
             // Run "phpdoc"
@@ -89,19 +151,8 @@ protected function execute(InputInterface $input, OutputInterface $output)
                 : sprintf('Default structure.xml file "%s" not found.', $xml));
         }
 
-        if (!is_dir($outDir)) {
-            if (!mkdir($outDir)) {
-                throw new RuntimeException('out directory doesn\'t exist and cannot be created');
-            }
-        }
-
         $output->write(sprintf('Writing output to <fg=white>%s</>... ', $outDir));
 
-        // YAML dump configuration
-        $inline = 11; // The level where you switch to inline YAML
-        $indent = 2; // The amount of spaces to use for indentation of nested nodes
-        $flags = Yaml::DUMP_MULTI_LINE_LITERAL_BLOCK;
-
         $valid = true;
         $tocItems = [];
         $packageDescription = $component->getDescription();
@@ -196,19 +247,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
 
         if ($stagingBucket = $input->getOption('staging-bucket')) {
             $output->write(sprintf('Running docuploader to upload to staging bucket <fg=white>%s</>... ', $stagingBucket));
-            $process = new Process([
-                'docuploader',
-                'upload',
-                $outDir,
-                '--staging-bucket',
-                $stagingBucket,
-                '--destination-prefix',
-                'docfx-',
-                '--metadata-file',
-                 // use "realdir" until https://github.com/googleapis/docuploader/issues/132 is fixed
-                realpath($outDir) . '/docs.metadata'
-            ]);
-            $process->mustRun();
+            $this->uploadToStagingBucket($outDir, $stagingBucket);
             $output->writeln('Done.');
         }
 
@@ -284,4 +323,21 @@ private function getProtoPackageToNamespaceMap(bool $useFileCache): array
 
         return $item->get();
     }
+
+    private function uploadToStagingBucket(string $outDir, string $stagingBucket): void
+    {
+        $process = new Process([
+            'docuploader',
+            'upload',
+            $outDir,
+            '--staging-bucket',
+            $stagingBucket,
+            '--destination-prefix',
+            'docfx-',
+            '--metadata-file',
+             // use "realdir" until https://github.com/googleapis/docuploader/issues/132 is fixed
+            realpath($outDir) . '/docs.metadata'
+        ]);
+        $process->mustRun();
+    }
 }
diff --git a/dev/tests/Unit/Command/DocFxCommandTest.php b/dev/tests/Unit/Command/DocFxCommandTest.php
@@ -194,6 +194,24 @@ public function testNewClientMagicMethods()
         $this->assertGreaterThan(0, count($asyncMethods));
     }
 
+    public function testProductNeutralGuides()
+    {
+        self::getCommandTester()->execute([
+            '--generate-product-neutral-guides' => true,
+            '--out' => $tmpDir = sys_get_temp_dir() . '/' . rand(),
+            '--metadata-version' => '1.0.0',
+        ]);
+
+        $generatedFiles = array_diff(scandir($tmpDir), ['..', '.']);
+        $this->assertEquals([
+            'authentication.md',
+            'debug.md',
+            'docs.metadata',
+            'migrating.md',
+            'toc.yml',
+        ], array_values($generatedFiles));
+    }
+
     private function assertFileEqualsWithDiff(string $left, string $right, bool $updateFixtures = false)
     {
         if (file_get_contents($left) !== file_get_contents($right)) {