feat(docs): publish protobuf to refdocs

.kokoro/docs/publish.sh

@@ -60,6 +60,16 @@ $PROJECT_DIR/dev/google-cloud docfx \
     $STAGING_FLAG \
     $VERBOSITY_FLAG
 
+# Add protobuf
+PROTOBUF_DIR=$PROJECT_DIR/dev/vendor/google/protobuf
+PROTOBUF_VERSION=$(composer info google/protobuf -f json | jq .versions[0])
+$PROJECT_DIR/dev/google-cloud docfx \
+    --path $PROTOBUF_DIR \
+    --out protobuf-out \
+    --metadata-version $PROTOBUF_VERSION \
+    $STAGING_FLAG \
+    $VERBOSITY_FLAG
+
 # Add product-neutral guides
 $PROJECT_DIR/dev/google-cloud docfx \
     --generate-product-neutral-guides \

composer.json

@@ -856,5 +856,6 @@
     },
     "bin": [
         "Core/bin/google-cloud-batch"
-    ]
+    ],
+    "minimum-stability": "RC"
 }

dev/src/Component.php

@@ -28,6 +28,7 @@
 class Component
 {
     const VERSION_REGEX = '/^V([0-9])?(p[0-9])?(beta|alpha)?[0-9]?$/';
+    private const PROTOBUF = 'google/protobuf';
     public const ROOT_DIR = __DIR__ . '/../../';
     private string $path;
     private string $releaseLevel;
@@ -188,7 +189,10 @@ private function validateComponentFiles(): void
         $this->description = $composerJson['description'];
         $this->composerVersion = $composerJson['version'] ?? null;
 
-        if (!$repoName = $composerJson['extra']['component']['target'] ?? null) {
+        if ($this->packageName === Component::PROTOBUF) {
+            // special handling for protobuf "virtual" package
+            $repoName = 'protocolbuffers/protobuf';
+        } elseif (!$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'
@@ -204,6 +208,13 @@ private function validateComponentFiles(): void
             $repoMetadataJson = $repoMetadataFullJson[$this->name];
         } elseif (file_exists($repoMetadataPath = $this->path . '/.repo-metadata.json')) {
             $repoMetadataJson = json_decode(file_get_contents($repoMetadataPath), true);
+        } elseif ($this->packageName === Component::PROTOBUF) {
+            // special handling for protobuf "virtual" package
+            $repoMetadataJson = [
+                'release_level' => 'stable',
+                'client_documentation' => 'https://cloud.google.com/php/docs/reference/auth/latest',
+                'library_type' => 'CORE',
+            ];
         } else {
             throw new RuntimeException(sprintf(
                 'repo metadata not found for component "%s" and no .repo-metadata.json file found in %s',
@@ -218,16 +229,22 @@ private function validateComponentFiles(): void
                 $this->name
             ));
         }
-        if (empty($repoMetadataJson['release_level'])) {
+        if (empty($repoMetadataJson['client_documentation'])) {
             throw new RuntimeException(sprintf(
                 'repo metadata does not contain "client_documentation" for component "%s"',
                 $this->name
             ));
         }
+        if (empty($repoMetadataJson['library_type'])) {
+            throw new RuntimeException(sprintf(
+                'repo metadata does not contain "library_type" for component "%s"',
+                $this->name
+            ));
+        }
         $this->releaseLevel = $repoMetadataJson['release_level'];
         $this->clientDocumentation = $repoMetadataJson['client_documentation'];
-        $this->productDocumentation = $repoMetadataJson['product_documentation'] ?? '';
         $this->libraryType = $repoMetadataJson['library_type'];
+        $this->productDocumentation = $repoMetadataJson['product_documentation'] ?? '';
 
         $namespaces = [];
         foreach ($composerJson['autoload']['psr-4'] as $namespace => $dir) {
@@ -261,13 +278,20 @@ private function validateComponentFiles(): void
                 $this->componentDependencies[] = new Component('CommonProtos');
             }
         }
+        // add protobuf if it's required
+        if (isset($composerJson['require']['google/protobuf'])) {
+            $this->componentDependencies[] = new Component('protobuf', self::ROOT_DIR . '/dev/vendor/google/protobuf');
+        }
     }
 
     /**
      * Get the contents of VERSION in the component directory
      */
     public function getPackageVersion(): string
     {
+        if (!file_exists(sprintf('%s/VERSION', $this->path))) {
+            return '';
+        }
         return trim(file_get_contents(sprintf('%s/VERSION', $this->path)));
     }
 

dev/src/DocFx/Node/XrefTrait.php

@@ -187,9 +187,6 @@ private function replaceUidWithLink(string $uid, ?string $name = null): string
 
         // Check for external package namespaces
         switch (true) {
-            case str_starts_with($uid, '\Google\Protobuf\\'):
-                $extLinkRoot = 'https://protobuf.dev/reference/php/api-docs/';
-                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/fixtures/docfx/Vision/V1.AnnotateFileRequest.yml

@@ -117,7 +117,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::setFeatures()'
     name: setFeatures
@@ -206,7 +206,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::setPages()'
     name: setPages

dev/tests/fixtures/docfx/Vision/V1.AnnotateFileResponse.yml

@@ -120,7 +120,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateFileResponse::setResponses()'
     name: setResponses

dev/tests/fixtures/docfx/Vision/V1.AnnotateImageRequest.yml

@@ -112,7 +112,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageRequest::setFeatures()'
     name: setFeatures

dev/tests/fixtures/docfx/Vision/V1.AnnotateImageResponse.yml

@@ -142,7 +142,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setFaceAnnotations()'
     name: setFaceAnnotations
@@ -173,7 +173,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLandmarkAnnotations()'
     name: setLandmarkAnnotations
@@ -204,7 +204,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLogoAnnotations()'
     name: setLogoAnnotations
@@ -235,7 +235,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLabelAnnotations()'
     name: setLabelAnnotations
@@ -269,7 +269,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLocalizedObjectAnnotations()'
     name: setLocalizedObjectAnnotations
@@ -303,7 +303,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setTextAnnotations()'
     name: setTextAnnotations

dev/tests/fixtures/docfx/Vision/V1.AsyncAnnotateFileRequest.yml

@@ -119,7 +119,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncAnnotateFileRequest::setFeatures()'
     name: setFeatures

dev/tests/fixtures/docfx/Vision/V1.AsyncBatchAnnotateFilesRequest.yml

@@ -48,7 +48,7 @@ items:
           description: 'Optional. Target project and location to make a call. Format: `projects/{project-id}/locations/{location-id}`. If no parent is specified, a region will be chosen automatically. Supported location-ids: `us`: USA country only, `asia`: East asia areas, like Japan, Taiwan, `eu`: The European Union. Example: `projects/project-A/locations/eu`.'
         -
           id: '↳ labels'
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: 'Optional. The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateFilesRequest::getRequests()'
@@ -62,7 +62,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateFilesRequest::setRequests()'
     name: setRequests
@@ -148,7 +148,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateFilesRequest::setLabels()'
     name: setLabels
@@ -168,7 +168,7 @@ items:
       parameters:
         -
           id: var
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: ''
       returns:
         -

dev/tests/fixtures/docfx/Vision/V1.AsyncBatchAnnotateFilesResponse.yml

@@ -50,7 +50,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateFilesResponse::setResponses()'
     name: setResponses

dev/tests/fixtures/docfx/Vision/V1.AsyncBatchAnnotateImagesRequest.yml

@@ -55,7 +55,7 @@ items:
           description: 'Optional. Target project and location to make a call. Format: `projects/{project-id}/locations/{location-id}`. If no parent is specified, a region will be chosen automatically. Supported location-ids: `us`: USA country only, `asia`: East asia areas, like Japan, Taiwan, `eu`: The European Union. Example: `projects/project-A/locations/eu`.'
         -
           id: '↳ labels'
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: 'Optional. The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateImagesRequest::getRequests()'
@@ -69,7 +69,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateImagesRequest::setRequests()'
     name: setRequests
@@ -202,7 +202,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\AsyncBatchAnnotateImagesRequest::setLabels()'
     name: setLabels
@@ -222,7 +222,7 @@ items:
       parameters:
         -
           id: var
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: ''
       returns:
         -

dev/tests/fixtures/docfx/Vision/V1.BatchAnnotateFilesRequest.yml

@@ -47,7 +47,7 @@ items:
           description: 'Optional. Target project and location to make a call. Format: `projects/{project-id}/locations/{location-id}`. If no parent is specified, a region will be chosen automatically. Supported location-ids: `us`: USA country only, `asia`: East asia areas, like Japan, Taiwan, `eu`: The European Union. Example: `projects/project-A/locations/eu`.'
         -
           id: '↳ labels'
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: 'Optional. The labels with user-defined metadata for the request. Label keys and values can be no longer than 63 characters (Unicode codepoints), can only contain lowercase letters, numeric characters, underscores and dashes. International characters are allowed. Label values are optional. Label keys must start with a letter.'
   -
     uid: '\Google\Cloud\Vision\V1\BatchAnnotateFilesRequest::getRequests()'
@@ -63,7 +63,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\BatchAnnotateFilesRequest::setRequests()'
     name: setRequests
@@ -151,7 +151,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\BatchAnnotateFilesRequest::setLabels()'
     name: setLabels
@@ -171,7 +171,7 @@ items:
       parameters:
         -
           id: var
-          var_type: 'array|<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/MapField">Google\Protobuf\Internal\MapField</a>'
+          var_type: 'array|<xref uid="\Google\Protobuf\Internal\MapField">Google\Protobuf\Internal\MapField</xref>'
           description: ''
       returns:
         -

dev/tests/fixtures/docfx/Vision/V1.BatchAnnotateFilesResponse.yml

@@ -50,7 +50,7 @@ items:
     syntax:
       returns:
         -
-          var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
+          var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
   -
     uid: '\Google\Cloud\Vision\V1\BatchAnnotateFilesResponse::setResponses()'
     name: setResponses