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

docs: add process to build docs #125

Closed
silvolu opened this issue Aug 21, 2014 · 5 comments
Closed

docs: add process to build docs #125

silvolu opened this issue Aug 21, 2014 · 5 comments
Assignees
Labels
🚨 This issue needs some love. triage me I really want to be triaged.
Milestone

Comments

@silvolu
Copy link
Contributor

silvolu commented Aug 21, 2014

  • command to extract and generate .md/.html files in docs/
  • automated way to update gh-pages branch when the docs change
@silvolu silvolu added this to the M1: core, datastore & storage milestone Aug 21, 2014
@silvolu silvolu added the docs label Aug 21, 2014
@stephenplusplus
Copy link
Contributor

command to extract and generate .md/.html files in docs/

#127 - npm run docs will build the HTML + Markdown. 💃

automated way to update gh-pages branch when the docs change

Let's talk about this one :) It sounds nice to be able to accept a PR of source code changes, and have the docs generated. This is actually pretty doable, but with side effects.

If someone changes source code, sends a PR, the tests pass, and we merge it, we would want to

  • run npm docs to generate the docs directory,
  • commit the new files,
  • push the changes to master, and
  • push docs/html (the generated jsdoc directory) to gh-pages.

This doesn't feel too great, since we're letting a robot create a commit and push to master!

Travis will do whatever we say every time a PR is sent, and every time a commit is merged into master. It doesn't seem that we can do different things from different triggers. So, if someone changes source code, sends in a PR, the tests pass, but we don't merge it... Uh oh! Travis just kept on running, generated the docs, and pushed to master & gh-pages.

#127 currently has Travis push the docs/html folder from master into gh-pages after every successful PR-triggered Travis build & push to master. This is safer since even though it's running on every PR that passes the tests, it's using master as its source of truth.

So, that's the state of the task now. If you have any ideas for workarounds or know of other solutions, let me know.

@silvolu
Copy link
Contributor Author

silvolu commented Aug 22, 2014

Sorry, I made a great job in being unclear on the second point, what I meant was pushing the docs after a merge into master that affects the docs, which is what you did :)

We might move the docs step from Travis to the CI that we use to run the build that includes the regression tests, but this looks very good for now, thanks! Going through all the PRs now.

@ryanseys
Copy link
Contributor

Can we use PRs here too? i.e. A script will detect that docs are behind master (or latest tag), build docs, and auto create PR for updated docs. We then merge the PR manually. I prefer latest tag so we don't spam the PR/issues list & our inboxes. Thoughts?

Off-topic: Similar approach could be used for google/google-api-nodejs-client regeneration of APIs.

@silvolu
Copy link
Contributor Author

silvolu commented Aug 26, 2014

I'm not sure we want an additional PR.
JSDoc changes would be reviewed in the PR that affects them, and new docs generated when needed (when we merge into master or when we tag a new release).

@silvolu
Copy link
Contributor Author

silvolu commented Aug 27, 2014

Fixed in #127.

@silvolu silvolu closed this as completed Aug 27, 2014
@jgeewax jgeewax modified the milestones: M1: core, datastore & storage, Core Stable 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
sofisl pushed a commit that referenced this issue Oct 13, 2022
... chore: update gapic-generator-ruby to the latest commit chore: release gapic-generator-typescript 1.5.0

Committer: @miraleung
PiperOrigin-RevId: 380641501

Source-Link: googleapis/googleapis@076f7e9

Source-Link: googleapis/googleapis-gen@27e4c88
sofisl pushed a commit that referenced this issue Oct 13, 2022
sofisl pushed a commit that referenced this issue Nov 10, 2022
sofisl pushed a commit that referenced this issue Nov 11, 2022
This PR was generated using Autosynth. 🌈

Synth log will be available here:
https://source.cloud.google.com/results/invocations/9f0ce149-63bd-4aad-917d-44f82c8912a6/targets

- [ ] To automatically regenerate this PR, check this box.

Source-Link: googleapis/synthtool@ba9918c
sofisl pushed a commit that referenced this issue Nov 11, 2022
sofisl pushed a commit that referenced this issue Nov 11, 2022
sofisl pushed a commit that referenced this issue Nov 11, 2022
See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
sofisl pushed a commit that referenced this issue Nov 11, 2022
* chore(main): release 2.1.1

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
sofisl pushed a commit that referenced this issue Nov 11, 2022
Co-authored-by: Benjamin E. Coe <[email protected]>
sofisl pushed a commit that referenced this issue Nov 11, 2022
fix: use google-gax v3.3.0
Source-Link: googleapis/synthtool@c73d112
Post-Processor: gcr.io/cloud-devrel-public-resources/owlbot-nodejs:latest@sha256:b15a6f06cc06dcffa11e1bebdf1a74b6775a134aac24a0f86f51ddf728eb373e
sofisl pushed a commit that referenced this issue Nov 11, 2022
🤖 I have created a release *beep* *boop*
---


## [2.0.3](https://togithub.com/googleapis/nodejs-org-policy/compare/v2.0.2...v2.0.3) (2022-11-11)


### Bug Fixes

* Allow passing gax instance to client constructor ([#126](https://togithub.com/googleapis/nodejs-org-policy/issues/126)) ([c7147d4](https://togithub.com/googleapis/nodejs-org-policy/commit/c7147d40a9ed114ec42997d49c2f5dfcff948aad))
* **deps:** Use google-gax v3.5.2 ([#134](https://togithub.com/googleapis/nodejs-org-policy/issues/134)) ([0f1bfb0](https://togithub.com/googleapis/nodejs-org-policy/commit/0f1bfb0007ade736c2ec91f32ff187c80b2d6761))
* Do not import the whole google-gax from proto JS ([#1553](https://togithub.com/googleapis/nodejs-org-policy/issues/1553)) ([#125](https://togithub.com/googleapis/nodejs-org-policy/issues/125)) ([068b0a5](https://togithub.com/googleapis/nodejs-org-policy/commit/068b0a55fe805cedab9e66f62071c8be56f465ed))
* Preserve default values in x-goog-request-params header ([#128](https://togithub.com/googleapis/nodejs-org-policy/issues/128)) ([3f80014](https://togithub.com/googleapis/nodejs-org-policy/commit/3f80014a3c75311555df6cfde8470ae1f72a686f))
* Regenerated protos JS and TS definitions ([#137](https://togithub.com/googleapis/nodejs-org-policy/issues/137)) ([1606459](https://togithub.com/googleapis/nodejs-org-policy/commit/1606459c847f2ed945dccc8e43d57d273fac7ea9))
* use google-gax v3.3.0 ([068b0a5](https://togithub.com/googleapis/nodejs-org-policy/commit/068b0a55fe805cedab9e66f62071c8be56f465ed))

---
This PR was generated with [Release Please](https://togithub.com/googleapis/release-please). See [documentation](https://togithub.com/googleapis/release-please#release-please).
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 Jan 26, 2023
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
Co-authored-by: Benjamin E. Coe <[email protected]>
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