Skip to content

Commit bdbdf4b

Browse files
bshafferbshaffer
committed
feat(docs): publish protobuf to refdocs
1 parent b37d5e4 commit bdbdf4b

48 files changed

Lines changed: 147 additions & 108 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.kokoro/docs/publish.sh‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,16 @@ $PROJECT_DIR/dev/google-cloud docfx \
6060
$STAGING_FLAG \
6161
$VERBOSITY_FLAG
6262

63+
# Add protobuf
64+
PROTOBUF_DIR=$PROJECT_DIR/dev/vendor/google/protobuf
65+
PROTOBUF_VERSION=$(composer info google/protobuf -f json | jq .versions[0])
66+
$PROJECT_DIR/dev/google-cloud docfx \
67+
--path $PROTOBUF_DIR \
68+
--out protobuf-out \
69+
--metadata-version $PROTOBUF_VERSION \
70+
$STAGING_FLAG \
71+
$VERBOSITY_FLAG
72+
6373
# Add product-neutral guides
6474
$PROJECT_DIR/dev/google-cloud docfx \
6575
--generate-product-neutral-guides \

‎dev/src/Command/DocFxCommand.php‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -297,7 +297,10 @@ private function validate(ClassNode $class, OutputInterface $output): bool
297297
{
298298
$valid = true;
299299
$emptyRef = '<options=bold>empty</>';
300-
$isGenerated = $class->isProtobufMessageClass() || $class->isProtobufEnumClass() || $class->isServiceClass();
300+
$isGenerated = $class->isProtobufMessageClass()
301+
|| $class->isProtobufEnumClass()
302+
|| $class->isServiceClass()
303+
|| $class->isProtobufLibrary();
301304
foreach (array_merge([$class], $class->getMethods(), $class->getConstants()) as $node) {
302305
foreach ($this->getInvalidXrefs($node->getContent()) as $invalidRef) {
303306
if (isset(self::$allowedReferenceFailures[$node->getFullname()])

‎dev/src/Component.php‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@
2828
class Component
2929
{
3030
const VERSION_REGEX = '/^V([0-9])?(p[0-9])?(beta|alpha)?[0-9]?$/';
31+
private const PROTOBUF = 'google/protobuf';
3132
public const ROOT_DIR = __DIR__ . '/../../';
3233
private string $path;
3334
private string $releaseLevel;
@@ -188,7 +189,10 @@ private function validateComponentFiles(): void
188189
$this->description = $composerJson['description'];
189190
$this->composerVersion = $composerJson['version'] ?? null;
190191

191-
if (!$repoName = $composerJson['extra']['component']['target'] ?? null) {
192+
if ($this->packageName === Component::PROTOBUF) {
193+
// special handling for protobuf "virtual" package
194+
$repoName = 'protocolbuffers/protobuf';
195+
} elseif (!$repoName = $composerJson['extra']['component']['target'] ?? null) {
192196
if (!str_starts_with($composerJson['homepage'], 'https://github.com/')) {
193197
throw new RuntimeException(
194198
'composer does not contain extra.component.target, and homepage is not a github URL'
@@ -204,6 +208,13 @@ private function validateComponentFiles(): void
204208
$repoMetadataJson = $repoMetadataFullJson[$this->name];
205209
} elseif (file_exists($repoMetadataPath = $this->path . '/.repo-metadata.json')) {
206210
$repoMetadataJson = json_decode(file_get_contents($repoMetadataPath), true);
211+
} elseif ($this->packageName === Component::PROTOBUF) {
212+
// special handling for protobuf "virtual" package
213+
$repoMetadataJson = [
214+
'release_level' => 'stable',
215+
'client_documentation' => 'https://cloud.google.com/php/docs/reference/auth/latest',
216+
'library_type' => 'CORE',
217+
];
207218
} else {
208219
throw new RuntimeException(sprintf(
209220
'repo metadata not found for component "%s" and no .repo-metadata.json file found in %s',
@@ -218,16 +229,22 @@ private function validateComponentFiles(): void
218229
$this->name
219230
));
220231
}
221-
if (empty($repoMetadataJson['release_level'])) {
232+
if (empty($repoMetadataJson['client_documentation'])) {
222233
throw new RuntimeException(sprintf(
223234
'repo metadata does not contain "client_documentation" for component "%s"',
224235
$this->name
225236
));
226237
}
238+
if (empty($repoMetadataJson['library_type'])) {
239+
throw new RuntimeException(sprintf(
240+
'repo metadata does not contain "library_type" for component "%s"',
241+
$this->name
242+
));
243+
}
227244
$this->releaseLevel = $repoMetadataJson['release_level'];
228245
$this->clientDocumentation = $repoMetadataJson['client_documentation'];
229-
$this->productDocumentation = $repoMetadataJson['product_documentation'] ?? '';
230246
$this->libraryType = $repoMetadataJson['library_type'];
247+
$this->productDocumentation = $repoMetadataJson['product_documentation'] ?? '';
231248

232249
$namespaces = [];
233250
foreach ($composerJson['autoload']['psr-4'] as $namespace => $dir) {
@@ -261,13 +278,20 @@ private function validateComponentFiles(): void
261278
$this->componentDependencies[] = new Component('CommonProtos');
262279
}
263280
}
281+
// add protobuf if it's required
282+
if (isset($composerJson['require']['google/protobuf'])) {
283+
$this->componentDependencies[] = new Component('protobuf', self::ROOT_DIR . '/dev/vendor/google/protobuf');
284+
}
264285
}
265286

266287
/**
267288
* Get the contents of VERSION in the component directory
268289
*/
269290
public function getPackageVersion(): string
270291
{
292+
if (!file_exists(sprintf('%s/VERSION', $this->path))) {
293+
return '';
294+
}
271295
return trim(file_get_contents(sprintf('%s/VERSION', $this->path)));
272296
}
273297

‎dev/src/DocFx/Node/ClassNode.php‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,11 @@ public function isProtobufMessageClass(): bool
7070
return false;
7171
}
7272

73+
public function isProtobufLibrary(): bool
74+
{
75+
return 0 === strpos($this->getNamespace(), '\Google\Protobuf');
76+
}
77+
7378
public function isGapicEnumClass(): bool
7479
{
7580
// returns true if the class extends \Google\Protobuf\Internal\Message

‎dev/src/DocFx/Node/XrefTrait.php‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -187,9 +187,6 @@ private function replaceUidWithLink(string $uid, ?string $name = null): string
187187

188188
// Check for external package namespaces
189189
switch (true) {
190-
case str_starts_with($uid, '\Google\Protobuf\\'):
191-
$extLinkRoot = 'https://protobuf.dev/reference/php/api-docs/';
192-
break;
193190
case 0 === strpos($uid, '\GuzzleHttp\Promise\PromiseInterface'):
194191
$extLinkRoot = 'https://docs.aws.amazon.com/aws-sdk-php/v3/api/class-GuzzleHttp.Promise.Promise.html';
195192
break;

‎dev/tests/fixtures/docfx/Vision/V1.AnnotateFileRequest.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,7 @@ items:
117117
syntax:
118118
returns:
119119
-
120-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
120+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
121121
-
122122
uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::setFeatures()'
123123
name: setFeatures
@@ -206,7 +206,7 @@ items:
206206
syntax:
207207
returns:
208208
-
209-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
209+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
210210
-
211211
uid: '\Google\Cloud\Vision\V1\AnnotateFileRequest::setPages()'
212212
name: setPages

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ items:
120120
syntax:
121121
returns:
122122
-
123-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
123+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
124124
-
125125
uid: '\Google\Cloud\Vision\V1\AnnotateFileResponse::setResponses()'
126126
name: setResponses

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,7 @@ items:
112112
syntax:
113113
returns:
114114
-
115-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
115+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
116116
-
117117
uid: '\Google\Cloud\Vision\V1\AnnotateImageRequest::setFeatures()'
118118
name: setFeatures

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -142,7 +142,7 @@ items:
142142
syntax:
143143
returns:
144144
-
145-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
145+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
146146
-
147147
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setFaceAnnotations()'
148148
name: setFaceAnnotations
@@ -173,7 +173,7 @@ items:
173173
syntax:
174174
returns:
175175
-
176-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
176+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
177177
-
178178
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLandmarkAnnotations()'
179179
name: setLandmarkAnnotations
@@ -204,7 +204,7 @@ items:
204204
syntax:
205205
returns:
206206
-
207-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
207+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
208208
-
209209
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLogoAnnotations()'
210210
name: setLogoAnnotations
@@ -235,7 +235,7 @@ items:
235235
syntax:
236236
returns:
237237
-
238-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
238+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
239239
-
240240
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLabelAnnotations()'
241241
name: setLabelAnnotations
@@ -269,7 +269,7 @@ items:
269269
syntax:
270270
returns:
271271
-
272-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
272+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
273273
-
274274
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setLocalizedObjectAnnotations()'
275275
name: setLocalizedObjectAnnotations
@@ -303,7 +303,7 @@ items:
303303
syntax:
304304
returns:
305305
-
306-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
306+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
307307
-
308308
uid: '\Google\Cloud\Vision\V1\AnnotateImageResponse::setTextAnnotations()'
309309
name: setTextAnnotations

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ items:
119119
syntax:
120120
returns:
121121
-
122-
var_type: '<a href="https://protobuf.dev/reference/php/api-docs/Google/Protobuf/Internal/RepeatedField">Google\Protobuf\Internal\RepeatedField</a>'
122+
var_type: '<xref uid="\Google\Protobuf\Internal\RepeatedField">Google\Protobuf\Internal\RepeatedField</xref>'
123123
-
124124
uid: '\Google\Cloud\Vision\V1\AsyncAnnotateFileRequest::setFeatures()'
125125
name: setFeatures

0 commit comments

Comments
 (0)