Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate docs and host on googlecloudplatform.github.io/gcloud-node ? #19

Closed
jgeewax opened this issue Jul 16, 2014 · 12 comments
Closed
Assignees
Labels
🚨 This issue needs some love. triage me I really want to be triaged.
Milestone

Comments

@jgeewax
Copy link
Contributor

jgeewax commented Jul 16, 2014

Some options I've seen:


I personally really like the docs for Express: http://expressjs.com/3x/api.html

@rakyll
Copy link
Contributor

rakyll commented Jul 21, 2014

My personal choice is dox, it works nicely with jsdoc and allows examples to be documented inline. The downside is that it doesn't generate pages, but provides JSON with extracted meta information.

@rakyll
Copy link
Contributor

rakyll commented Jul 29, 2014

@aliafshar is working with another person on the gcloud homepage. Once they come up with an initial template, we can generate Dox docs.

@stephenplusplus
Copy link
Contributor

@rakyll can you catch this issue up with any developments? I'm happy to start going through the code and adding examples, as well as spreading the readme out to new .md files.

@silvolu
Copy link
Contributor

silvolu commented Aug 12, 2014

@stephenplusplus I have a meeting today at 14 Pacific to discuss about templates etc.
Starting to add examples through the code sounds good to me, unless @rakyll has some other coding tasks in mind for you.

@stephenplusplus
Copy link
Contributor

Hope the meeting went well! I played around with JSDoc today - here's an example of Dataset, the generated Markdown, and its source.

@rakyll
Copy link
Contributor

rakyll commented Aug 13, 2014

unless @rakyll has some other coding tasks in mind for you.

SGTM.

@silvolu
Copy link
Contributor

silvolu commented Aug 13, 2014

@stephenplusplus could you put the PubSub refactoring on ice for the moment and work on docs for Datastore and Storage? we need to focus on completing M1, and PubSub is not part of it. Thanks!

@stephenplusplus
Copy link
Contributor

I would be happy to! I believe I linked to an example of a js doc overhaul
of Datastore.dataset earlier in this thread. Any thoughts on that before I
move on to other sections?

Something worth noticing, which I'm sure I don't need to point out, is the
cumbersome dominance of the doc blocks once you add examples in. I foresee
maintenance of the blocks being an area of trouble, as it's not always
obvious which examples include a piece of an API that you're refactoring.

As an example, if I change the Query object and update the examples in its
query.js file, I might not know to look for the example of using a Query
object which was shown as part of the Dataset.runQuery documentation in
dataset.js. We can try to isolate examples to prevent this, but it ends up
hurting the quality of the examples, as no example would be a complete
"start to finish" example.

Hope that made sense. The only alternative I can think of to address the
problem would be simply splitting the current readme up into different
sections, then putting complete usage examples there.

Just things to keep in mind!

On Wednesday, August 13, 2014, Silvano Luciani notifications@github.com
wrote:

@stephenplusplus https://github.com/stephenplusplus could you put the
PubSub refactoring on ice for the moment and work on docs for Datastore and
Storage? we need to focus on completing M1, and PubSub is not part of it.
Thanks!


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

@silvolu
Copy link
Contributor

silvolu commented Aug 13, 2014

The PoC looks good to me, and in the end, as long as we're adding jsdoc, it will be easy to switch to Dox or similar.

Regarding the maintenance problem, I think themaintaining samples not directly related to an API change would also apply to several .md files containing the docs. At least in this way we make sure that we can update the example directly related to a change, because it will sit in the file that we're changing :). Makes sense?

@stephenplusplus
Copy link
Contributor

Sure. Just to clarify the splitting of files, I meant to suggest one
"Datastore" md doc, one "PubSub" etc, so your find and replace would be
limited to one file. Maintenance-made-easy probably is not a realistic
endeavor, so either option will bring us as close as we can get :)

On Wednesday, August 13, 2014, Silvano Luciani notifications@github.com
wrote:

The PoC looks good to me, and in the end, as long as we're adding jsdoc,
it will be easy to switch to Dox or similar.

Regarding the maintenance problem, I think themaintaining samples not
directly related to an API change would also apply to several .md files
containing the docs. At least in this way we make sure that we can update
the example directly related to a change, because it will sit in the file
that we're changing :). Makes sense?


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

@stephenplusplus stephenplusplus self-assigned this Aug 13, 2014
@stephenplusplus stephenplusplus mentioned this issue Aug 14, 2014
@stephenplusplus
Copy link
Contributor

Closing this since we have this launched. I'm sure we'll have tweaks as we go, but since we're live, I think we can take them on one by one. Feel free to re-open if you feel there's more to discuss.

@silvolu
Copy link
Contributor

silvolu commented Aug 27, 2014

Sorry for being a pedant, but we're still waiting for the correct templates, I'll consider this launched when those are in place :)

@silvolu silvolu reopened this Aug 27, 2014
@rakyll rakyll closed this as completed Sep 8, 2014
@jgeewax jgeewax added this to the Core Stable milestone Feb 2, 2015
@yoshi-automation yoshi-automation added triage me I really want to be triaged. 🚨 This issue needs some love. labels Apr 6, 2020
chingor13 pushed a commit that referenced this issue Aug 26, 2022
chingor13 pushed a commit that referenced this issue Sep 12, 2022
chingor13 pushed a commit that referenced this issue Sep 13, 2022
chingor13 pushed a commit that referenced this issue Sep 14, 2022
sofisl pushed a commit that referenced this issue Nov 11, 2022
PiperOrigin-RevId: 380817131
sofisl pushed a commit that referenced this issue Nov 11, 2022
* chore(deps): upgrade gapic-generator-java to 2.4.1

PiperOrigin-RevId: 422607515

Source-Link: googleapis/googleapis@ba2ffd6

Source-Link: googleapis/googleapis-gen@73ba4ad
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNzNiYTRhZGQyMzlhNjE5ZGE1NjdmZmJkNGU1NzMwZmRkNmRlMDRkMyJ9

* 🦉 Updates from OwlBot

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>
sofisl pushed a commit that referenced this issue Nov 12, 2022
- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 474338479

Source-Link: googleapis/googleapis@d5d35e0

Source-Link: googleapis/googleapis-gen@efcd3f9
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZWZjZDNmOTM5NjJhMTAzZjY4ZjAwM2UyYTFlZWNkZTZmYTIxNmEyNyJ9
sofisl pushed a commit that referenced this issue Nov 16, 2022
PiperOrigin-RevId: 362943541

Source-Author: Google APIs <noreply@google.com>
Source-Date: Mon Mar 15 08:17:12 2021 -0700
Source-Repo: googleapis/googleapis
Source-Sha: cb631dd3ffe0d6f77f7b01c5168e357771c74b51
Source-Link: googleapis/googleapis@cb631dd
sofisl pushed a commit that referenced this issue Nov 16, 2022
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
sofisl pushed a commit that referenced this issue Nov 17, 2022
sofisl pushed a commit that referenced this issue Dec 21, 2022
* add try/catch to delete operations in testing

* refactor test file; use timestamp for resource names, clean up resources over an hour old, move create and delete operations to before and after hooks in each test suite

* 🦉 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>
sofisl pushed a commit that referenced this issue Jan 10, 2023
- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 468790263

Source-Link: googleapis/googleapis@873ab45

Source-Link: googleapis/googleapis-gen@cb6f37a
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiY2I2ZjM3YWVmZjJhMzQ3MmU0MGE3YmJhY2U4YzY3ZDc1ZTI0YmVlNSJ9
sofisl pushed a commit that referenced this issue Feb 23, 2023
- [ ] Regenerate this pull request now.

PiperOrigin-RevId: 474338479

Source-Link: googleapis/googleapis@d5d35e0

Source-Link: googleapis/googleapis-gen@efcd3f9
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiZWZjZDNmOTM5NjJhMTAzZjY4ZjAwM2UyYTFlZWNkZTZmYTIxNmEyNyJ9
sofisl pushed a commit that referenced this issue Feb 23, 2023
🤖 I have created a release *beep* *boop*
---


## [0.2.0](googleapis/nodejs-dataform@v0.1.0...v0.2.0) (2022-09-14)


### Features

* Release API version v1beta1 (no changes to v1alpha2) ([#11](googleapis/nodejs-dataform#11)) ([1ff35a6](googleapis/nodejs-dataform@1ff35a6))


### Bug Fixes

* Allow passing gax instance to client constructor ([#18](googleapis/nodejs-dataform#18)) ([34e62f5](googleapis/nodejs-dataform@34e62f5))
* Better support for fallback mode ([#13](googleapis/nodejs-dataform#13)) ([f48d918](googleapis/nodejs-dataform@f48d918))
* Change import long to require ([#14](googleapis/nodejs-dataform#14)) ([3790bfd](googleapis/nodejs-dataform@3790bfd))
* Do not import the whole google-gax from proto JS ([#1553](https://github.com/googleapis/nodejs-dataform/issues/1553)) ([#17](googleapis/nodejs-dataform#17)) ([32373fd](googleapis/nodejs-dataform@32373fd))
* Preserve default values in x-goog-request-params header ([#19](googleapis/nodejs-dataform#19)) ([bbb3790](googleapis/nodejs-dataform@bbb3790))
* Remove pip install statements ([#1546](https://github.com/googleapis/nodejs-dataform/issues/1546)) ([#15](googleapis/nodejs-dataform#15)) ([71f0add](googleapis/nodejs-dataform@71f0add))
* use google-gax v3.3.0 ([32373fd](googleapis/nodejs-dataform@32373fd))

---
This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🚨 This issue needs some love. triage me I really want to be triaged.
Projects
None yet
Development

No branches or pull requests

5 participants