Skip to content

Conversation

@jdpedrie
Copy link
Contributor

@jdpedrie jdpedrie commented Mar 3, 2017

This change adds the generated GAPIC clients to the Google Cloud PHP docs site. It takes advantage of GoogleCloudPlatform/gcloud-common#213, so we'll need to rebuild the docs site before this is merged.

  • Add all generated clients to the table of contents.
  • Add simple landing pages (README.md) in empty folders.
  • Modify doc generator to recognize external types specified in docs/external-classes.json and transform references into external links.

For an example, see https://jdpedrie.github.io/gcloud-php/#/docs/master/servicebuilder.

This closes #99.

@googlebot googlebot added the cla: yes This human has signed the Contributor License Agreement. label Mar 3, 2017
foreach ($types as &$type) {
// object is a PHPDoc keyword so it is not capable of detecting the context
// https://github.com/phpDocumentor/ReflectionDocBlock/blob/2.0.4/src/phpDocumentor/Reflection/DocBlock/Type/Collection.php#L37
if ($type === 'Object') {

This comment was marked as spam.

@dwsupplee dwsupplee added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Mar 3, 2017
@dwsupplee
Copy link
Contributor

Cool stuff! A few notes:

@michaelbausor
Copy link
Contributor

Filed an issue to update those docs: googleapis/gapic-generator#1089

@jdpedrie
Copy link
Contributor Author

jdpedrie commented Mar 3, 2017

@michaelbausor do you know of any reference documentation for Grpc\ChannelCredentials which I could link to? grpc.io has API documentation for the PHP library only, not for classes created by the extension.

@michaelbausor
Copy link
Contributor

Not that I'm aware of. It is coming from here: https://github.com/grpc/grpc/blob/master/src/php/ext/grpc/call_credentials.h#L49

@dwsupplee
Copy link
Contributor

Docs for classes like Grpc\ChannelCredentials would be incredibly helpful. That seems like something we should push for.

@jdpedrie Besides the aforementioned, it looks like there are other types that are not being linked out to. serviceFilter and timeRange found in ErrorStatsServiceClient::listEvents are examples of others. Scrolling through the docs I'm seeing them rather frequently. Can we do a review to make sure they're all getting hit?

@dwsupplee dwsupplee mentioned this pull request Mar 3, 2017
@jdpedrie
Copy link
Contributor Author

jdpedrie commented Mar 3, 2017

@michaelbausor one more thing...

https://github.com/GoogleCloudPlatform/google-cloud-php/blob/master/src/Monitoring/V3/MetricServiceClient.php

Lots of links in this file that will not work on the docs site.

For instance:

[filter](/monitoring/api/v3/filters)

Looks like they all just need to be prefixed with https://cloud.google.com.

@jdpedrie
Copy link
Contributor Author

jdpedrie commented Mar 3, 2017

@dwsupplee updated the rest of the refs to external classes I could find (save ChannelCredentials) and regenerated the docs site on my fork.

@dwsupplee
Copy link
Contributor

👊

@dwsupplee dwsupplee merged commit 3c2c02d into googleapis:master Mar 7, 2017
@jdpedrie jdpedrie deleted the gapic-docs branch June 9, 2017 13:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla: yes This human has signed the Contributor License Agreement. do not merge Indicates a pull request not ready for merge, due to either quality or timing. documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Link to GAX classes from docs site

4 participants