feat(docs): generate reference docs for GAX (#7797)

.kokoro/docs/publish.sh

@@ -17,39 +17,38 @@ PROJECT_DIR=$(dirname $(dirname $SCRIPT_DIR))
 if [ ! -d 'dev/vendor/' ]; then
     composer install -d $PROJECT_DIR/dev
 fi
-
+STAGING_FLAG="";
 if [ "$STAGING_BUCKET" != "" ]; then
     echo "Using staging bucket ${STAGING_BUCKET}..."
+    STAGING_FLAG="--staging-bucket $STAGING_BUCKET"
 fi
-VERBOSITY="";
+VERBOSITY_FLAG="";
 if [ "$GCLOUD_DEBUG" = "1" ]; then
     echo "Setting verbosity to VERBOSE...";
-    VERBOSITY=" -v";
+    VERBOSITY_FLAG=" -v";
 fi
-
 find $PROJECT_DIR/* -mindepth 1 -maxdepth 1 -name 'composer.json' -not -path '*vendor/*' -regex "$PROJECT_DIR/[A-Z].*" -exec dirname {} \; | while read DIR
 do
     COMPONENT=$(basename $DIR)
     VERSION=$(cat $DIR/VERSION)
-    if [ "$STAGING_BUCKET" != "" ]; then
-        $PROJECT_DIR/dev/google-cloud docfx \
-            --component $COMPONENT \
-            --out $DIR/out \
-            --metadata-version $VERSION \
-            --staging-bucket $STAGING_BUCKET \
-            --with-cache \
-            $VERBOSITY
-    else
-        # dry run
-        $PROJECT_DIR/dev/google-cloud docfx \
-            --component $COMPONENT \
-            --out $DIR/out \
-            --metadata-version $VERSION \
-            --with-cache \
-            $VERBOSITY
-    fi
+    $PROJECT_DIR/dev/google-cloud docfx \
+        --component $COMPONENT \
+        --out $DIR/out \
+        --metadata-version $VERSION \
+        --with-cache \
+        $STAGING_FLAG \
+        $VERBOSITY_FLAG
 done
 
+# Add GAX repo
+GAX_DIR=$PROJECT_DIR/dev/vendor/google/gax
+$PROJECT_DIR/dev/google-cloud docfx \
+    --path $GAX_DIR \
+    --out gax-out \
+    --metadata-version $(cat $GAX_DIR/VERSION) \
+    $STAGING_FLAG \
+    $VERBOSITY_FLAG
+
 # If this run after a release, store the released artifacts.
 if [ "$KOKORO_GITHUB_COMMIT" != "" ]; then
     # Move to the project directory

dev/src/Command/DocFxCommand.php

@@ -55,16 +55,11 @@ protected function configure()
         $this->setName('docfx')
             ->setDescription('Generate DocFX yaml from a phpdoc strucutre.xml')
             ->addOption('xml', '', InputOption::VALUE_REQUIRED, 'Path to phpdoc structure.xml')
-            ->addOption('component', 'c', InputOption::VALUE_REQUIRED, 'Generate docs only for a single component.', '')
+            ->addOption('component', 'c', InputOption::VALUE_REQUIRED, 'Generate docs for a specific component.', '')
             ->addOption('out', '', InputOption::VALUE_REQUIRED, 'Path where to store the generated output.', 'out')
             ->addOption('metadata-version', '', InputOption::VALUE_REQUIRED, 'version to write to docs.metadata using docuploader')
             ->addOption('staging-bucket', '', InputOption::VALUE_REQUIRED, 'Upload to the specified staging bucket using docuploader.')
-            ->addOption(
-                'component-path',
-                '',
-                InputOption::VALUE_OPTIONAL,
-                'Specify the path of the desired component. Please note, this option is only intended for testing purposes.'
-            )
+            ->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')
         ;
     }
@@ -75,8 +70,9 @@ protected function execute(InputInterface $input, OutputInterface $output)
             throw new RuntimeException('This command must be run on PHP 8.0 or above');
         }
 
-        $componentName = rtrim($input->getOption('component'), '/') ?: basename(getcwd());
-        $component = new Component($componentName, $input->getOption('component-path'));
+        $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');

dev/src/Component.php

@@ -170,9 +170,6 @@ private function validateComponentFiles(): void
         if (empty($composerJson['name'])) {
             throw new RuntimeException('composer.json does not contain "name"');
         }
-        if (empty($composerJson['extra']['component']['target'])) {
-            throw new RuntimeException('composer does not contain extra.component.target');
-        }
         if (empty($composerJson['description'])) {
             throw new RuntimeException('composer.json does not contain "description"');
         }
@@ -181,22 +178,32 @@ private function validateComponentFiles(): void
         }
 
         $this->packageName = $composerJson['name'];
-        $repoName = $composerJson['extra']['component']['target'];
-        $this->repoName = preg_replace('/\.git$/', '', $repoName); // Strip trailing ".git"
         $this->description = $composerJson['description'];
 
-        $repoMetadataPath = self::ROOT_DIR . '/.repo-metadata-full.json';
-        $repoMetadataFullJson = json_decode(file_get_contents($repoMetadataPath), true);
-        if (!$repoMetadataFullJson) {
-            throw new RuntimeException('Invalid .repo-metadata-full.json');
+        if (!$repoName = $composerJson['extra']['component']['target'] ?? null) {
+            if (!str_starts_with($composerJson['homepage'], 'https://github.com/')) {
+                throw new RuntimeException(
+                    'composer does not contain extra.component.target, and homepage is not a github URL'
+                );
+            }
+            $repoName = str_replace('https://github.com', '', $composerJson['homepage']);
         }
-        if (!isset($repoMetadataFullJson[$this->name])) {
+        $this->repoName = preg_replace('/\.git$/', '', $repoName); // Strip trailing ".git"
+
+        $repoMetadataFullPath = self::ROOT_DIR . '/.repo-metadata-full.json';
+        $repoMetadataFullJson = json_decode(file_get_contents($repoMetadataFullPath), true);
+        if (isset($repoMetadataFullJson[$this->name])) {
+            $repoMetadataJson = $repoMetadataFullJson[$this->name];
+        } elseif (file_exists($repoMetadataPath = $this->path . '/.repo-metadata.json')) {
+            $repoMetadataJson = json_decode(file_get_contents($repoMetadataPath), true);
+        } else {
             throw new RuntimeException(sprintf(
-                'repo metadata for component "%s" not found in .repo-metadata-full.json',
-                $this->name
+                'repo metadata not found for component "%s" and no .repo-metadata.json file found in %s',
+                $this->name,
+                $repoMetadataPath
             ));
         }
-        $repoMetadataJson = $repoMetadataFullJson[$this->name];
+
         if (empty($repoMetadataJson['release_level'])) {
             throw new RuntimeException(sprintf(
                 'repo metadata does not contain "release_level" for component "%s"',
@@ -234,10 +241,11 @@ private function validateComponentFiles(): void
                 $this->componentDependencies[] = new Component($componentName);
             }
         }
-        if (isset($composerJson['require']['google/gax'])
-            && !isset($composerJson['require']['google/common-protos'])
-        ) {
-            $this->componentDependencies[] = new Component('CommonProtos');
+        if (isset($composerJson['require']['google/gax'])) {
+            $this->componentDependencies[] = new Component('gax', self::ROOT_DIR . '/dev/vendor/google/gax');
+            if (!isset($composerJson['require']['google/common-protos'])) {
+                $this->componentDependencies[] = new Component('CommonProtos');
+            }
         }
     }
 

dev/src/DocFx/Node/XrefTrait.php

@@ -170,24 +170,12 @@ private function replaceUidWithLink(string $uid, string $name = null): string
 
         // Check for external package namespaces
         switch (true) {
-            case str_starts_with($uid, '\Google\ApiCore\\'):
-                $extLinkRoot = 'https://googleapis.github.io/gax-php#';
-                break;
             case str_starts_with($uid, '\Google\Auth\\'):
                 $extLinkRoot = 'https://googleapis.github.io/google-auth-library-php/main/';
                 break;
             case str_starts_with($uid, '\Google\Protobuf\\'):
                 $extLinkRoot = 'https://protobuf.dev/reference/php/api-docs/';
                 break;
-            case str_starts_with($uid, '\Google\Api\\'):
-            case str_starts_with($uid, '\Google\Cloud\Iam\V1\\'):
-            case str_starts_with($uid, '\Google\Cloud\Location\\'):
-            case str_starts_with($uid, '\Google\Cloud\Logging\Type\\'):
-            case str_starts_with($uid, '\Google\Iam\\'):
-            case str_starts_with($uid, '\Google\Rpc\\'):
-            case str_starts_with($uid, '\Google\Type\\'):
-                $extLinkRoot = 'https://googleapis.github.io/common-protos-php#';
-                break;
             case 0 === strpos($uid, '\GuzzleHttp\Promise\PromiseInterface'):
                 $extLinkRoot = 'https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html';
                 break;

dev/tests/Unit/Command/DocFxCommandTest.php

@@ -141,7 +141,7 @@ public function provideDocFxFiles()
             '--xml' => self::$fixturesDir . '/phpdoc/structure.xml',
             '--out' => self::$tmpDir = sys_get_temp_dir() . '/' . rand(),
             '--metadata-version' => '1.0.0',
-            '--component-path' => self::$fixturesDir . '/component/Vision',
+            '--path' => self::$fixturesDir . '/component/Vision',
             '--with-cache' => true,
         ]);