From b664d41eb20bb286cd4d0f34210d1eb280fec49c Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Wed, 22 May 2024 11:16:39 -0400 Subject: [PATCH 1/6] Add docgen all script and update documentation --- .github/workflows/check-docs.yml | 10 ++++++---- CONTRIBUTING.md | 4 ++-- package.json | 1 + 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index aefab2506e3..d96c97160b5 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -name: Doc Change Check (Run "yarn docgen devsite" if this fails) +name: Doc Change Check (Run "yarn docgen:all" if this fails) on: pull_request @@ -33,10 +33,12 @@ jobs: node-version: 20.x - name: Yarn install run: yarn - - name: Run doc generation (devsite docs) - run: yarn docgen devsite + - name: Run doc generation + run: yarn docgen:all - name: Check for changes in docs-devsite dir (fail if so) run: git diff --exit-code docs-devsite + - name: Check for changes in toc dir (fail if so) + run: git diff --exit-code toc - name: Reference documentation needs to be updated. See message below. if: ${{ failure() }} - run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen devsite\` locally to regenerate docs and add them to this PR." \ No newline at end of file + run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen:all\` locally to regenerate docs and add them to this PR." \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d504afe7833..a46419ef04c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -228,10 +228,10 @@ root directory to generate the documentation locally: ``` yarn -yarn docgen devsite +yarn docgen:all ``` -This will generate reference docs in `docs-devsite/`. Commit and push the generated +This will generate reference docs in `docs-devsite/` and `/toc`. Commit and push the generated documentation changes to GitHub following the [PR submission guidelines](#submit). Your push to the remote repository should force any failing documentation checks to execute again. diff --git a/package.json b/package.json index 0f11f89a6ce..179899adf32 100644 --- a/package.json +++ b/package.json @@ -40,6 +40,7 @@ "test:saucelabs": "node scripts/run_saucelabs.js", "docgen": "ts-node-script scripts/docgen/docgen.ts", "docgen:compat": "node scripts/docgen-compat/generate-docs.js --api js", + "docgen:all": "yarn docgen devsite && yarn docgen toc", "lint": "lerna run --scope @firebase/* lint", "lint:fix": "lerna run --scope @firebase/* lint:fix", "size-report": "ts-node-script scripts/size_report/report_binary_size.ts", From 3186c59b0f5ae1d94021922f5b339c6af71974e3 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 23 May 2024 13:19:01 -0400 Subject: [PATCH 2/6] Move toc to devsite, and rename to `_toc.yaml` --- toc/toc.yaml => docs-devsite/_toc.yaml | 6 ------ scripts/docgen/docgen.ts | 11 +++++++++++ 2 files changed, 11 insertions(+), 6 deletions(-) rename toc/toc.yaml => docs-devsite/_toc.yaml (98%) diff --git a/toc/toc.yaml b/docs-devsite/_toc.yaml similarity index 98% rename from toc/toc.yaml rename to docs-devsite/_toc.yaml index d6d5ff4a185..43ec97cda56 100644 --- a/toc/toc.yaml +++ b/docs-devsite/_toc.yaml @@ -472,8 +472,6 @@ toc: path: /docs/reference/js/vertexai-preview.date_2.md - title: EnhancedGenerateContentResponse path: /docs/reference/js/vertexai-preview.enhancedgeneratecontentresponse.md - - title: ErrorDetails - path: /docs/reference/js/vertexai-preview.errordetails.md - title: FileData path: /docs/reference/js/vertexai-preview.filedata.md - title: FileDataPart @@ -517,8 +515,6 @@ toc: path: /docs/reference/js/vertexai-preview.groundingattribution.md - title: GroundingMetadata path: /docs/reference/js/vertexai-preview.groundingmetadata.md - - title: HTTPErrorDetails - path: /docs/reference/js/vertexai-preview.httperrordetails.md - title: InlineDataPart path: /docs/reference/js/vertexai-preview.inlinedatapart.md - title: ModelParams @@ -545,8 +541,6 @@ toc: path: /docs/reference/js/vertexai-preview.usagemetadata.md - title: VertexAI path: /docs/reference/js/vertexai-preview.vertexai.md - - title: VertexAIError - path: /docs/reference/js/vertexai-preview.vertexaierror.md - title: VertexAIOptions path: /docs/reference/js/vertexai-preview.vertexaioptions.md - title: VideoMetadata diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index 314e42a7cfc..4103558e334 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -152,12 +152,23 @@ async function generateToc() { 'toc', '--input', 'temp', + '--output', + 'docs-devsite', '-p', '/docs/reference/js', '-j' ], { stdio: 'inherit' } ); + // The toc on the devsite must be named _toc.yaml + await spawn( + 'mv', + [ + 'docs-devsite/toc.yaml', + 'docs-devsite/_toc.yaml' + ], + { stdio: 'inherit' } + ); } finally { cleanup(); } From 7525d512c8baa9d9c68a7de56752b560af99bd48 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 23 May 2024 13:24:25 -0400 Subject: [PATCH 3/6] Fix formatting --- scripts/docgen/docgen.ts | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/scripts/docgen/docgen.ts b/scripts/docgen/docgen.ts index 4103558e334..8e9dfa87cab 100644 --- a/scripts/docgen/docgen.ts +++ b/scripts/docgen/docgen.ts @@ -161,14 +161,9 @@ async function generateToc() { { stdio: 'inherit' } ); // The toc on the devsite must be named _toc.yaml - await spawn( - 'mv', - [ - 'docs-devsite/toc.yaml', - 'docs-devsite/_toc.yaml' - ], - { stdio: 'inherit' } - ); + await spawn('mv', ['docs-devsite/toc.yaml', 'docs-devsite/_toc.yaml'], { + stdio: 'inherit' + }); } finally { cleanup(); } From e8076c3584342e42b39cfdfd1ab88f4ac7767825 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 23 May 2024 13:40:29 -0400 Subject: [PATCH 4/6] Remove seperate toc CI check --- .github/workflows/check-docs.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/workflows/check-docs.yml b/.github/workflows/check-docs.yml index d96c97160b5..6e8a84d2a2d 100644 --- a/.github/workflows/check-docs.yml +++ b/.github/workflows/check-docs.yml @@ -37,8 +37,6 @@ jobs: run: yarn docgen:all - name: Check for changes in docs-devsite dir (fail if so) run: git diff --exit-code docs-devsite - - name: Check for changes in toc dir (fail if so) - run: git diff --exit-code toc - name: Reference documentation needs to be updated. See message below. if: ${{ failure() }} run: echo "Changes in this PR affect the reference docs. Run \`yarn docgen:all\` locally to regenerate docs and add them to this PR." \ No newline at end of file From 0fb39f6b150edd779d0eaa4c1ffca881ad23d4cc Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Thu, 23 May 2024 13:42:16 -0400 Subject: [PATCH 5/6] Update Contributing guide --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a46419ef04c..fe164af9176 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -231,7 +231,7 @@ yarn yarn docgen:all ``` -This will generate reference docs in `docs-devsite/` and `/toc`. Commit and push the generated +This will generate reference docs and the toc in `docs-devsite/`. Commit and push the generated documentation changes to GitHub following the [PR submission guidelines](#submit). Your push to the remote repository should force any failing documentation checks to execute again. From a3e4f4212088b8491c7c27c29319253ec97d3d55 Mon Sep 17 00:00:00 2001 From: Daniel La Rocque Date: Mon, 3 Jun 2024 15:18:17 -0500 Subject: [PATCH 6/6] revert changes made to refdocs --- docs-devsite/_toc.yaml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs-devsite/_toc.yaml b/docs-devsite/_toc.yaml index 43ec97cda56..d6d5ff4a185 100644 --- a/docs-devsite/_toc.yaml +++ b/docs-devsite/_toc.yaml @@ -472,6 +472,8 @@ toc: path: /docs/reference/js/vertexai-preview.date_2.md - title: EnhancedGenerateContentResponse path: /docs/reference/js/vertexai-preview.enhancedgeneratecontentresponse.md + - title: ErrorDetails + path: /docs/reference/js/vertexai-preview.errordetails.md - title: FileData path: /docs/reference/js/vertexai-preview.filedata.md - title: FileDataPart @@ -515,6 +517,8 @@ toc: path: /docs/reference/js/vertexai-preview.groundingattribution.md - title: GroundingMetadata path: /docs/reference/js/vertexai-preview.groundingmetadata.md + - title: HTTPErrorDetails + path: /docs/reference/js/vertexai-preview.httperrordetails.md - title: InlineDataPart path: /docs/reference/js/vertexai-preview.inlinedatapart.md - title: ModelParams @@ -541,6 +545,8 @@ toc: path: /docs/reference/js/vertexai-preview.usagemetadata.md - title: VertexAI path: /docs/reference/js/vertexai-preview.vertexai.md + - title: VertexAIError + path: /docs/reference/js/vertexai-preview.vertexaierror.md - title: VertexAIOptions path: /docs/reference/js/vertexai-preview.vertexaioptions.md - title: VideoMetadata