Revert "Update 'Vespa-CLI' reference documentation." (#3307)

* Revert "Update 'Vespa-CLI' reference documentation." This reverts commit 2339f04. * Revert "test workflows" This reverts commit efdb5cd. * Revert "fix(CI): push changes to the documentation with PR" This reverts commit b692efd.
vespa-engine · Aug 12, 2024 · aeedfd4 · aeedfd4
1 parent 2339f04
commit aeedfd4
Show file tree

Hide file tree

Showing 24 changed files with 128 additions and 260 deletions.
diff --git a/.github/actions/commit-updated-docs/action.yml b/.github/actions/commit-updated-docs/action.yml
diff --git a/.github/workflows/auto-update-documentation.yml b/.github/workflows/auto-update-documentation.yml
@@ -9,8 +9,10 @@ on:
   schedule:
     - cron: "0 0 * * *"
 
-  push:
-    branches: [push-via-pr] # Test the workflow by pushing to this branch
+  repository_dispatch:
+    types:
+      - update-vespa-version
+      - update-vespa-cli-doc
 
 permissions:
   contents: write
@@ -22,20 +24,13 @@ defaults:
     # Ref: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#defaultsrunshell
     shell: bash
 
-# Limit concurrency to better handle commit and push operations.
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-
 jobs:
   update-vespa-version:
     #
     # This job updates the Vespa version in the documentation.
     #
     runs-on: ubuntu-24.04
 
-    concurrency:
-      group: docs-update
-
     steps:
       - uses: actions/checkout@v4
 
@@ -44,31 +39,33 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y xq
 
-      - name: Update Vespa version
-        id: update-docs
+      - name: Get Latest Vespa version
         env:
           ENABLE_PUSH: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}
         run: |
           VESPA_VERSION=$(curl -sSL https://repo1.maven.org/maven2/com/yahoo/vespa/parent/maven-metadata.xml | \
            xq -x '/metadata/versioning/latest')
 
           echo "Vespa version: $VESPA_VERSION"
-          echo "version=$VESPA_VERSION" >> $GITHUB_OUTPUT
 
-          # Update the Vespa version in the documentation configuration file.
           sed -i'' "s/\(vespa_version:\) \"[0-9\.]*\"/\1 \"${VESPA_VERSION}\"/" _config.yml
-
           git diff
-          echo "has-changes=$(git status --short | wc -l)" >> $GITHUB_OUTPUT
 
-      - name: Commit changes
-        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
-        uses: ./.github/actions/commit-updated-docs
-        with:
-          commit-message: "Update Vespa version to ${{ steps.vespa-metadata.outputs.version }}."
-          files: _config.yml
-          # push: ${{ env.ENABLE_PUSH == 'true' }}
-          push: "true"
+          # Check if there are changes to commit.
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "Updating Vespa version in documentation to ${VESPA_VERSION}" >> $GITHUB_STEP_SUMMARY
+            git config --global user.email "[email protected]"
+            git config --global user.name "${{ github.actor}}"
+
+            git add _config.yml
+            git commit -m "Update Vespa-version to ${VESPA_VERSION}. MERGEOK"
+            git pull --rebase
+
+            # Only push if the event is a push and the branch is the default branch.
+            if [[ "${{ env.ENABLE_PUSH }}" == "true" ]]; then
+              git push
+            fi
+          fi
 
   update-vespa-cli-doc:
     #
@@ -80,17 +77,13 @@ jobs:
       VESPA_CLI_DOC_DIR: en/reference/vespa-cli
       ENABLE_PUSH: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}
 
-    concurrency:
-      group: docs-update
-
     steps:
       - uses: actions/checkout@v4
 
       - name: Install Vespa CLI
         uses: vespa-engine/setup-vespa-cli-action@v1
 
       - name: Generate Vespa CLI Documentation
-        id: update-docs
         working-directory: ${{ env.VESPA_CLI_DOC_DIR }}
         run: |
           vespa gendoc .
@@ -109,15 +102,21 @@ jobs:
           sed -i'' 's#\(https://[a-z.]*vespa.ai/[^[:space:]]*\)#[\1](\1)#g' *.md
 
           git diff
-          echo "has-changes=$(git status --short | wc -l)" >> $GITHUB_OUTPUT
 
-      - name: Commit changes
-        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
-        uses: ./.github/actions/commit-updated-docs
-        with:
-          commit-message: "Update 'Vespa-CLI' reference documentation."
-          files: ${{ env.VESPA_CLI_DOC_DIR }}
-          push: "true"
+          # Check if there are changes to commit.
+          if [[ -n "$(git status --short)" ]]; then
+            echo "Updating Vespa CLI reference documentation" >> $GITHUB_STEP_SUMMARY
+            git config --global user.email "[email protected]"
+            git config --global user.name "${{ github.actor}}"
+
+            git add vespa*.md
+            git commit -m "Update 'Vespa-CLI' reference documentation. MERGEOK"
+            git pull --rebase
+
+            if [[ "${{ env.ENABLE_PUSH }}" == "true" ]]; then
+              git push
+            fi
+          fi
 
   update-metric-reference:
     #
@@ -129,9 +128,6 @@ jobs:
     env:
       ENABLE_PUSH: ${{ contains(fromJSON('["workflow_dispatch", "schedule"]'), github.event_name) && github.ref_name == 'master' }}
 
-    concurrency:
-      group: docs-update
-
     steps:
       - uses: actions/checkout@v4
 
@@ -152,8 +148,7 @@ jobs:
           echo "Using version: $VESPA_VERSION"
           echo "version=$VESPA_VERSION" >> $GITHUB_OUTPUT
 
-      - name: Update Metric Reference
-        id: update-docs
+      - name: Update to latest
         env:
           VESPA_VERSION: ${{ steps.vespa-metadata.outputs.version }}
         run: |
@@ -162,10 +157,16 @@ jobs:
 
           git diff
 
-      - name: Commit changes
-        if: ${{ steps.update-docs.outputs.has-changes != '0' }}
-        uses: ./.github/actions/commit-updated-docs
-        with:
-          commit-message: "Update 'Metric' reference documentation."
-          files: "en/reference/*-metrics-reference.html"
-          push: "true"
+          if [[ -n "$(git status --short en/reference/*-metrics-reference.html)" ]]; then
+            echo "Updating metric reference" >> $GITHUB_STEP_SUMMARY
+            git config --global user.email "[email protected]"
+            git config --global user.name "${{ github.actor}}"
+
+            git add en/reference/*-metrics-reference.html
+            git commit -m "Update 'Metric' reference documentation. MERGEOK"
+            git pull --rebase
+
+            if [[ "${{ env.ENABLE_PUSH }}" == "true" ]]; then
+              git push
+            fi
+          fi
diff --git a/en/reference/vespa-cli/vespa.md b/en/reference/vespa-cli/vespa.md
@@ -13,12 +13,7 @@ The command-line tool for Vespa.ai.
 
 Use it on Vespa instances running locally, remotely or in Vespa Cloud.
 
-To get started, see the following quick start guides:
-
-- Local Vespa instance: [https://docs.vespa.ai/en/vespa-quick-start.html](https://docs.vespa.ai/en/vespa-quick-start.html)
-- Vespa Cloud: [https://cloud.vespa.ai/en/getting-started](https://cloud.vespa.ai/en/getting-started)
-
-The complete Vespa documentation is available at https://docs.vespa.ai.
+Vespa documentation: https://docs.vespa.ai
 
 For detailed description of flags and configuration, see 'vespa help config'.
 
@@ -45,19 +40,19 @@ vespa [flags]
 * [vespa activate](vespa_activate.html)	 - Activate (deploy) a previously prepared application package
 * [vespa auth](vespa_auth.html)	 - Manage Vespa Cloud credentials
 * [vespa clone](vespa_clone.html)	 - Create files and directory structure from a Vespa sample application
+* [vespa completion](vespa_completion.html)	 - Generate the autocompletion script for the specified shell
 * [vespa config](vespa_config.html)	 - Manage persistent values for global flags
 * [vespa curl](vespa_curl.html)	 - Access Vespa directly using curl
 * [vespa deploy](vespa_deploy.html)	 - Deploy (prepare and activate) an application package
 * [vespa destroy](vespa_destroy.html)	 - Remove a deployed Vespa application and its data
 * [vespa document](vespa_document.html)	 - Issue a single document operation to Vespa
 * [vespa feed](vespa_feed.html)	 - Feed multiple document operations to Vespa
-* [vespa fetch](vespa_fetch.html)	 - Download a deployed application package
 * [vespa log](vespa_log.html)	 - Show the Vespa log
 * [vespa prepare](vespa_prepare.html)	 - Prepare an application package for activation
 * [vespa prod](vespa_prod.html)	 - Deploy an application package to production in Vespa Cloud
 * [vespa query](vespa_query.html)	 - Issue a query to Vespa
 * [vespa status](vespa_status.html)	 - Show Vespa endpoints and status
 * [vespa test](vespa_test.html)	 - Run a test suite, or a single test
 * [vespa version](vespa_version.html)	 - Show current CLI version and check for updates
-* [vespa visit](vespa_visit.html)	 - Retrieve and print all documents from Vespa
+* [vespa visit](vespa_visit.html)	 - Fetch and print all documents from Vespa
 
diff --git a/en/reference/vespa-cli/vespa_auth_api-key.md b/en/reference/vespa-cli/vespa_auth_api-key.md
@@ -11,9 +11,8 @@ Create a new developer key for headless authentication with Vespa Cloud control
 
 Create a new developer key for headless authentication with Vespa Cloud control plane
 
-A developer key is a tenant-wide secret, intended for headless communication
-with the Vespa Cloud control plane. For example when deploying from a continuous
-integration system.
+A developer key is intended for headless communication with the Vespa Cloud
+control plane. For example when deploying from a continuous integration system.
 
 The developer key will be stored in the Vespa CLI home directory
 (see 'vespa help config'). Other commands will then automatically load the developer
@@ -34,7 +33,7 @@ Note that when overriding the developer key through environment variables,
 that key will always be used. It's not possible to specify a tenant-specific
 key through the environment.
 
-See [https://cloud.vespa.ai/en/security/guide](https://cloud.vespa.ai/en/security/guide) for more details about developer keys.
+Read more in [https://cloud.vespa.ai/en/security/guide](https://cloud.vespa.ai/en/security/guide)
 
 ```
 vespa auth api-key [flags]

diff --git a/en/reference/vespa-cli/vespa_clone.md b/en/reference/vespa-cli/vespa_clone.md
@@ -9,13 +9,14 @@ Create files and directory structure from a Vespa sample application
 
 ### Synopsis
 
-Create files and directory structure from a Vespa sample application.
+Create files and directory structure from a Vespa sample application
+from a sample application.
 
 Sample applications are downloaded from
 https://github.com/vespa-engine/sample-apps.
 
 By default sample applications are cached in the user's cache directory. This
-directory can be overriden by setting the VESPA_CLI_CACHE_DIR environment
+directory can be overridden by setting the VESPA_CLI_CACHE_DIR environment
 variable.
 
 ```

diff --git a/en/reference/vespa-cli/vespa_config.md b/en/reference/vespa-cli/vespa_config.md
@@ -11,9 +11,9 @@ Manage persistent values for global flags
 
 Manage persistent values for global flags.
 
-This command allows setting persistent values for the global flags found in
-Vespa CLI. On future invocations the flag can then be omitted as it is read
-from the config file instead.
+This command allows setting persistent values for global flags. On future
+invocations the flag can then be omitted as it is read from the config file
+instead.
 
 Configuration is written to $HOME/.vespa by default. This path can be
 overridden by setting the VESPA_CLI_HOME environment variable.
@@ -36,16 +36,16 @@ The following global flags/options can be configured:
 application
 
 Specifies the application ID to manage. It has three parts, separated by
-dots, with the third part being optional. If the third part is omitted it
-defaults to "default". This is only relevant for the "cloud" and "hosted"
-targets. See [https://cloud.vespa.ai/en/tenant-apps-instances](https://cloud.vespa.ai/en/tenant-apps-instances) for more details.
-This has no default value. Examples: tenant1.app1, tenant1.app1.instance1
+dots, with the third part being optional. If the part is omitted it defaults to
+"default". This is only relevant for the "cloud" and "hosted" targets. See
+[https://cloud.vespa.ai/en/tenant-apps-instances](https://cloud.vespa.ai/en/tenant-apps-instances) for more details. This has no
+default value. Examples: tenant1.app1, tenant1.app1.instance1
 
 cluster
 
 Specifies the container cluster to manage. If left empty (default) and the
 application has only one container cluster, that cluster is chosen
-automatically. When an application has multiple cluster this must specify a
+automatically. When an application has multiple cluster this must be set a
 valid cluster name, as specified in services.xml. See
 [https://docs.vespa.ai/en/reference/services-container.html](https://docs.vespa.ai/en/reference/services-container.html) for more details.
 
@@ -58,9 +58,9 @@ colors if supported by the terminal, "never" completely disables colors and
 instance
 
 Specifies the instance of the application to manage. When specified, this takes
-precedence over the instance specified as part of the 'application' option.
-This has no default value and is only relevant for the "cloud" and "hosted"
-targets. Example: instance2
+precedence over the instance specified as part of application. This has no
+default value and is only relevant for the "cloud" and "hosted" targets.
+Example: instance2
 
 quiet
 
@@ -85,7 +85,7 @@ e.g. vespa deploy or vespa query. Possible values are:
 
 Authentication is configured automatically for the cloud and hosted targets. To
 set a custom private key and certificate, e.g. for use with a self-hosted Vespa
-installation configured with mTLS, see the documentation of 'vespa auth cert'.
+installation using mTLS, see the documentation of 'vespa cert'.
 
 zone
 
@@ -94,6 +94,7 @@ This is only relevant for cloud and hosted targets and defaults to a dev zone.
 See [https://cloud.vespa.ai/en/reference/zones](https://cloud.vespa.ai/en/reference/zones) for available zones. Examples:
 dev.aws-us-east-1c, dev.gcp-us-central1-f, perf.aws-us-east-1c
 
+
 ```
 vespa config [flags]
 ```

diff --git a/en/reference/vespa-cli/vespa_config_get.md b/en/reference/vespa-cli/vespa_config_get.md
@@ -26,6 +26,7 @@ vespa config get [option-name] [flags]
 $ vespa config get
 $ vespa config get target
 $ vespa config get --local
+
 ```
 
 ### Options

diff --git a/en/reference/vespa-cli/vespa_config_set.md b/en/reference/vespa-cli/vespa_config_set.md
@@ -27,7 +27,8 @@ $ vespa config set application my-tenant.my-application.my-instance
 $ vespa config set instance other-instance
 
 # Set an option in local configuration, for the current application only
-$ vespa config set --local zone perf.us-north-1
+$ vespa config set --local wait 600
+
 ```
 
 ### Options