googleapis/google-cloud-php

feat(docs): document how to generate and push documentation for a single component/version

bshaffer opened this issue · 1 comments

In order to enable versioning in our refdocs, we must be able to deploy a component version in the past (in the case of bug fixes). This is always possible, so we need to include the documentation somewhere. Add the documentation below somewhere (probably in the dev dir, or on our internal teams page).

The steps go something like this:

  1. check out this repo and go into the "dev" directory
    cd google-cloud-php/dev
  2. Create a new "build" directory to install the component/version
    mkdir build
  3. install the component and version you want to generate docs for (in this case, it's google/cloud-vision v1.2.0)
    composer require google/cloud-vision:1.2.0 -d build
  4. run the docfx command, setting the component path to the vendored package. Set the staging bucket and metadata version if you want to upload it
    ./google-cloud docfx \
      --component Vision \
      --component-path=build/vendor/google/cloud-vision \
      --metadata-version=1.2.0 \
      --staging-bucket=docs-staging-v2-dev

You're done!