docs: upstream links #790

callmehiphop · 2015-08-10T14:31:21Z

Closes #740

Added links for all upstream counterparts.

lib/bigquery/dataset.js

@@ -56,6 +56,9 @@ function Dataset(bigQuery, id) {
 /**
 * Create a table given a tableId or configuration object.
 *
+ * See [Tables: insert](https://cloud.google.com/bigquery/docs/reference/v2/tables/insert)


callmehiphop · 2015-08-10T15:55:04Z

@stephenplusplus so I kinda think the overall appearance of the links could be better, what are your feelings on doing something like this..

/**
 * <div class="notice">See [Tables: insert](https://cloud.google.com/bigquery/docs/reference/v2/tables/insert)
 * for more detailed information.</div>
 */

stephenplusplus · 2015-08-10T15:58:31Z

Could you post a screenshot of what that renders like?

callmehiphop · 2015-08-10T16:12:43Z

Initially I tried use blockquote markdown syntax (which works) but there isn't any styling associated with it. Alternatively I could write some CSS for that and we could go that route.

stephenplusplus · 2015-08-10T16:28:38Z

That looks cool to me. Semantics: would just a manual a tag be better?

callmehiphop · 2015-08-10T16:30:44Z

That looks cool to me. Semantics: would just a manual a tag be better?

Instead of the markdown link syntax? [text](http://link.com)?

stephenplusplus · 2015-08-10T16:32:16Z

Yeah, I'm thinking since we have to add a class, we don't need the extra
div wrapper if we just write out the a.

On Monday, August 10, 2015, Dave Gramlich notifications@github.com wrote:

That looks cool to me. Semantics: would just a manual a tag be better?

Instead of the markdown link syntax? text?

—
Reply to this email directly or view it on GitHub
#790 (comment)
.

callmehiphop · 2015-08-10T16:36:38Z

Well, if I understand correctly, that's going to turn the entire sentence into a link? I'm probably splitting hairs, but I think that would be kind of ugly. We could just write some styles to make the blockquote look the same as the notice class and go full out markdown.

stephenplusplus · 2015-08-10T16:44:29Z

Nope you're right. I'm just getting myself confused. Sorry!

For the text, wdyt about just "Official API documentation"

And if it's just the one line, we can use the a tag with a class, unless you think that's a bad idea.

Official API documentation.

stephenplusplus · 2015-08-11T00:44:21Z

It looks awesome! Moving the link to a jsdoc property makes it much easier to make changes now without having to go through all of the docs.

I would prefer the links move to the top, as we want to get across "see the API docs for more information about our parameters". Here's an example:

Can you think of another way to make it clear that the official docs have more information on the properties we accept?

Also note, I changed "Code on GitHub" to "Source Code". Small change, but "Code on GitHub" just reads like a bad sentence to me. "Source Code" is direct and concise!

callmehiphop · 2015-08-11T05:35:40Z

I would prefer the links move to the top, as we want to get across "see the API docs for more information about our parameters".

Done!

Can you think of another way to make it clear that the official docs have more information on the properties we accept?

I think maybe just make a note within the object description? e.g. - Configuration object. For a complete list of properties please refer to the Official API Documentation.

It's also possible to give each resource link a custom title from JSDoc, so we could alter the link title to convey this as well. Perhaps instead of Official API Documentation you could say Complete List of Configuration Options or something..

Also note, I changed "Code on GitHub" to "Source Code". Small change, but "Code on GitHub" just reads like a bad sentence to me. "Source Code" is direct and concise!

I can dig it.

stephenplusplus · 2015-08-12T02:00:44Z

LGTM.

@jgeewax wdyt? Did we make things better or regress?

jgeewax · 2015-08-12T22:26:03Z

So it's definitely a step forward, however... I have to say I liked the "See: Tables.insert [ -> ] for more information" since it ties it to the specific method (aka, I know I'm not being dumped off to some marketing landing page somewhere that's ridiculous...)

Is it too much work to do that? (Fully understand if so.)

Ideally, text might be something like...

"See: Tables.insert [ -> ] API method for more information"

callmehiphop · 2015-08-12T22:46:37Z

Is it too much work to do that?

It definitely isn't!

@stephenplusplus thought it would be nice to move the source code link into the same block and while doing that I also found links for concepts/references/etc. scattered across the api so I decided to consolidate them all. (e.g. http://callmehiphop.github.io/gcloud-node/#/docs/master/storage/bucket?method=acl)

Is that something you like and would want to keep? If so, I think maybe the verbiage "See: Tables.insert for more information" might sound kinda funny in a list of links opposed to something like "Tables.insert REST API Documentation"

Thoughts?

jgeewax · 2015-08-12T22:49:05Z

Gotcha

Phrased as a list of links, definitely "Tables.insert API documentation (official)" or similar makes sense

Is it crazy to move the resources down as well? Logically they make sense above, but when I'm looking at docs, examples are likely going to be ... far more important than the link to the API docs...

Maybe call it "More information" and put it at the bottom?

callmehiphop · 2015-08-12T23:09:19Z

Personally I think it makes sense - a user is probably only going to want to see the full documentation if the examples don't provide them with the information they need. So having the links below the examples is probably more convenient.

However, I think the whole reason @stephenplusplus opened an issue about this is because we don't document all the available options that a user can pass in for some methods. Having the links right above the options as well as a comment in the options description telling the user to visit the official API documentation kinda solved that.

stephenplusplus · 2015-08-13T01:28:30Z

How about this or something similar?

callmehiphop · 2015-08-13T02:15:14Z

Updated the link titles & placement and pushed, let me know what you guys think!

updated lint rules to ignore 80+ chars for comment urls created resource section added more descriptive link titles and moved resources to the bottom changed @apidocs to @resource

stephenplusplus · 2015-08-14T02:32:33Z

Awesome. Just. Awesome.

docs: upstream links

callmehiphop · 2015-08-14T02:34:02Z

💃

[![Mend Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [@google-cloud/storage](https://togithub.com/googleapis/nodejs-storage) | [`^5.0.0` -> `^6.0.0`](https://renovatebot.com/diffs/npm/@google-cloud%2fstorage/5.20.5/6.1.0) | [![age](https://badges.renovateapi.com/packages/npm/@google-cloud%2fstorage/6.1.0/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/npm/@google-cloud%2fstorage/6.1.0/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/npm/@google-cloud%2fstorage/6.1.0/compatibility-slim/5.20.5)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/npm/@google-cloud%2fstorage/6.1.0/confidence-slim/5.20.5)](https://docs.renovatebot.com/merge-confidence/) | --- ### Configuration 📅 **Schedule**: Branch creation - "after 9am and before 3pm" (UTC), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Renovate will not automatically rebase this PR, because other commits have been found. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, click this checkbox. ⚠ **Warning**: custom changes will be lost. --- This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-translate).

[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [sinon](https://sinonjs.org/) ([source](https://togithub.com/sinonjs/sinon)) | [`^9.0.2` -> `^10.0.0`](https://renovatebot.com/diffs/npm/sinon/9.2.4/10.0.0) | [![age](https://badges.renovateapi.com/packages/npm/sinon/10.0.0/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/npm/sinon/10.0.0/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/npm/sinon/10.0.0/compatibility-slim/9.2.4)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/npm/sinon/10.0.0/confidence-slim/9.2.4)](https://docs.renovatebot.com/merge-confidence/) | --- ### Release Notes <details> <summary>sinonjs/sinon</summary> ### [`v10.0.0`](https://togithub.com/sinonjs/sinon/blob/master/CHANGELOG.md#1000--2021-03-22) [Compare Source](https://togithub.com/sinonjs/sinon/compare/v9.2.4...v10.0.0) ================== - Upgrade nise to 4.1.0 - Use [@sinonjs/eslint-config](https://togithub.com/sinonjs/eslint-config)[@4](https://togithub.com/4) => Adopts ES2017 => Drops support for IE 11, Legacy Edge and legacy Safari </details> --- ### Renovate configuration :date: **Schedule**: "after 9am and before 3pm" (UTC). :vertical_traffic_light: **Automerge**: Disabled by config. Please merge this manually once you are satisfied. :recycle: **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. :no_bell: **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-dialogflow).

🤖 I have created a release \*beep\* \*boop\* --- ### [4.6.1](https://www.github.com/googleapis/nodejs-speech/compare/v4.6.0...v4.6.1) (2021-08-17) ### Bug Fixes * **deps:** google-gax v2.24.1 ([#790](https://www.github.com/googleapis/nodejs-speech/issues/790)) ([bd8ab29](https://www.github.com/googleapis/nodejs-speech/commit/bd8ab29d3b6480d854a8a3a23e520d09d6bdb298)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).

* docs: fix node release schedule link Co-authored-by: Jeffrey Rennie <rennie@google.com> Source-Link: googleapis/synthtool@1a24315 Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-nodejs:latest@sha256:e08f9a3757808cdaf7a377e962308c65c4d7eff12db206d4fae702dd50d43430 * chore!: upgrade to Node 14 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --------- Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com> Co-authored-by: Sofia Leon <sofialeon@google.com>

googlebot added the cla: yes This human has signed the Contributor License Agreement. label Aug 10, 2015

callmehiphop added docs labels Aug 10, 2015

stephenplusplus reviewed Aug 10, 2015
View reviewed changes

callmehiphop added don't merge and removed don't merge labels Aug 10, 2015

callmehiphop removed the don't merge label Aug 10, 2015

callmehiphop changed the title ~~Upstream links~~ docs: upstream links Aug 12, 2015

stephenplusplus mentioned this pull request Aug 12, 2015

Support Google Compute Engine #792

Merged

18 tasks

docs: add upstream links

7cf51e2

updated lint rules to ignore 80+ chars for comment urls created resource section added more descriptive link titles and moved resources to the bottom changed @apidocs to @resource

stephenplusplus added a commit that referenced this pull request Aug 14, 2015

Merge pull request #790 from callmehiphop/upstream-links

173c5f9

docs: upstream links

stephenplusplus merged commit 173c5f9 into googleapis:master Aug 14, 2015

callmehiphop deleted the upstream-links branch August 14, 2015 02:34

stephenplusplus mentioned this pull request Aug 30, 2015

Find a way to share the HTML + CSS for our gcloud-* docs ? googleapis/google-cloud-python#1094

Closed

stephenplusplus mentioned this pull request Jul 5, 2017

Add easy link from docs to the code #2430

Closed

sofisl mentioned this pull request Nov 10, 2022

migrate code from googleapis/nodejs-translate #3520

Merged

4 tasks

sofisl mentioned this pull request Nov 11, 2022

migrate code from googleapis/nodejs-dialogflow #3546

Merged

4 tasks

sofisl mentioned this pull request Jan 17, 2023

migrate code from googleapis/nodejs-vision #3860

Merged

4 tasks

sofisl pushed a commit that referenced this pull request Jan 17, 2023

feat(secrets): begin migration to secret manager from keystore (#790)

a368d0d

sofisl pushed a commit that referenced this pull request Jan 24, 2023

fix(deps): google-gax v2.24.1 (#790)

731e0d3

sofisl pushed a commit that referenced this pull request Jan 25, 2023

fix(deps): google-gax v2.24.1 (#790)

1960f81

sofisl mentioned this pull request Sep 13, 2023

migrate code from googleapis/nodejs-automl #4655

Closed

4 tasks

sofisl mentioned this pull request Sep 14, 2023

migrate code from googleapis/nodejs-automl #4656

Merged

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: upstream links #790

docs: upstream links #790

callmehiphop commented Aug 10, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

stephenplusplus commented Aug 11, 2015

callmehiphop commented Aug 11, 2015

stephenplusplus commented Aug 12, 2015

jgeewax commented Aug 12, 2015

callmehiphop commented Aug 12, 2015

jgeewax commented Aug 12, 2015

callmehiphop commented Aug 12, 2015

stephenplusplus commented Aug 13, 2015

callmehiphop commented Aug 13, 2015

stephenplusplus commented Aug 14, 2015

callmehiphop commented Aug 14, 2015

docs: upstream links #790

docs: upstream links #790

Conversation

callmehiphop commented Aug 10, 2015

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

This comment was marked as spam.

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

callmehiphop commented Aug 10, 2015

stephenplusplus commented Aug 10, 2015

stephenplusplus commented Aug 11, 2015

callmehiphop commented Aug 11, 2015

stephenplusplus commented Aug 12, 2015

jgeewax commented Aug 12, 2015

callmehiphop commented Aug 12, 2015

jgeewax commented Aug 12, 2015

callmehiphop commented Aug 12, 2015

stephenplusplus commented Aug 13, 2015

callmehiphop commented Aug 13, 2015

stephenplusplus commented Aug 14, 2015

callmehiphop commented Aug 14, 2015