From 72800c3fd74f1d1cd866fc3672f2611d58262756 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 13 May 2026 14:33:27 +0530 Subject: [PATCH 1/5] template addition --- modules/ROOT/pages/3rd-party-script.adoc | 72 ------------------------ modules/_templates/concept.adoc | 32 +++++++++++ modules/_templates/procedure.adoc | 46 +++++++++++++++ modules/_templates/reference.adoc | 36 ++++++++++++ modules/_templates/release-notes.adoc | 29 ++++++++++ 5 files changed, 143 insertions(+), 72 deletions(-) delete mode 100644 modules/ROOT/pages/3rd-party-script.adoc create mode 100644 modules/_templates/concept.adoc create mode 100644 modules/_templates/procedure.adoc create mode 100644 modules/_templates/reference.adoc create mode 100644 modules/_templates/release-notes.adoc diff --git a/modules/ROOT/pages/3rd-party-script.adoc b/modules/ROOT/pages/3rd-party-script.adoc deleted file mode 100644 index a978ada50..000000000 --- a/modules/ROOT/pages/3rd-party-script.adoc +++ /dev/null @@ -1,72 +0,0 @@ -= External tools and script integration -:toc: true -:toclevels: 2 - -:page-title: Integrate external tools and allow scripts -:page-pageid: external-tool-script-integration -:page-description: Security settings for embedding - -ThoughtSpot supports integrating third-party apps such as Mixpanel, Pendo, LogRocket, and more in your embed. If you are using third-party tools to track usage, trace, log, or onboard your application users, you can seamlessly integrate these tools with ThoughtSpot embed and add custom JavaScript. This feature is disabled by default on ThoughtSpot instances. To enable this feature, contact ThoughtSpot Support. - -[IMPORTANT] -==== -While ThoughtSpot allows the injection of custom JavaScript, it is important to be aware of the associated security risks, particularly Cross-Site Scripting (XSS). XSS is a vulnerability that can enable malicious actors to inject and execute unauthorized scripts within a trusted environment. This can lead to data breaches, unauthorized access to user sessions, and compromised system integrity. ThoughtSpot strongly recommends reviewing security guidelines before activating this feature in your instances and exercising caution when integrating third-party tools into your embedded application. -==== - -== Security considerations - -Before requesting ThoughtSpot Support to enable this feature on your instance, do the following: - -* Review the security risks associated with custom-hosted scripts and understand the potential consequences of XSS attacks. -* Implement security controls and measures to validate hosted scripts and mitigate potential vulnerabilities. - -== Feature enablement - -Enabling third-party tools on embed involves two steps: - -. Request for feature activation and provide the script details to ThoughtSpot Support -. Adding the script sources to the CSP allowlist - -=== Request for feature enablement - -Create a ThoughtSpot Support ticket to enable the feature on your instance. In your request, specify the domain URLs that will host the scripts in your embedding environment. - -Wait for ThoughtSpot Support to validate and approve, and then add the domain that hosts the script to the CSP allowlist on your instance. This step will ensure that only the trusted and vetted domains are allowed to run scripts in your application environment. - -=== Add script source to CSP allowlist -After the script hosting URL is approved and configured by ThoughtSpot Support, you must add the JavaScript hosting domain to the CSP allowlist. This step requires administration privileges, so make sure you log in to ThoughtSpot with your administrator credentials. - -. In your ThoughtSpot application, navigate to *Develop* > *Customizations* > *Security Settings*. -. If your instance has the Orgs feature enabled, ensure that you are in the *All Orgs* context. -. On the *Security Settings* page, click *Edit* and turn on the *CSP script-src domains* toggle switch. -+ -[.widthAuto] -[.bordered] -image::./images/csp-script-domain.png[CSS script-src domain] -. Add the script hosting domain. -. Click *Save changes*. - -[NOTE] -==== -* The *CSP script-src domains* section is visible to users with administrative privileges only if the third-party integration feature is enabled on your instance. -* The *CSP script-src domains* cannot be enabled and configured at the Org level. When configured, this setting will apply to all the Orgs configured on your instance. -==== - -=== Allow Websocket endpoints -If your tool uses WebSockets, add the tool’s `wss://` endpoint to the CSP and CORS allowlists in ThoughtSpot. This enables secure WebSocket connections from an embedded ThoughtSpot page to the tool's WebSocket endpoint without being blocked by the browser’s Content Security Policy. - -Only hosts explicitly listed with `wss://` are permitted. You can add `wss://` URL in the **Develop** > **Security Settings** page. - -== Passing variables to the hosted script - -To pass variables to the customer's hosted script, Visual Embed SDK provides the `customVariablesForThirdPartyTools` parameter. The `customVariablesForThirdPartyTools` is an object containing the variables that you wish to pass to the customer’s hosted JavaScript. These may include private information such as credentials or keys. The hosted JavaScript will access these variables via the `window.tsEmbed` object. - -Developers can define this parameter in the **init()** function as shown in the following example. Once initialized, the JavaScript will run after the authentication is successfully completed in the ThoughtSpot Embed App. - -[source,JavaScript] ----- -init({ - //... - customVariablesForThirdPartyTools: { cloud: "123Basic" } -}); ----- diff --git a/modules/_templates/concept.adoc b/modules/_templates/concept.adoc new file mode 100644 index 000000000..9ed7514fc --- /dev/null +++ b/modules/_templates/concept.adoc @@ -0,0 +1,32 @@ += +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: concept +:page-role: +:product-version: +:jira-ref: +// author: +// last-reviewed: + +// 1-2 sentence lead: what this concept is and why it matters. + +== How works + +// Explanation. Use diagrams (image::) where spatial relationships matter. +// Avoid procedure steps here — link to procedure pages instead. + +== Key components + +// Optional. Use a definition list for named parts: +Component name:: +Description of what it does. + +== Limitations and constraints + +// Known limitations, version-specific behaviour, or edge cases. +// TODO: verify with engineering + +== Related information + +* xref::/page.adoc[Link text] diff --git a/modules/_templates/procedure.adoc b/modules/_templates/procedure.adoc new file mode 100644 index 000000000..11a91ab2c --- /dev/null +++ b/modules/_templates/procedure.adoc @@ -0,0 +1,46 @@ += +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: procedure +:page-role: +:product-version: +:jira-ref: +// author: +// last-reviewed: + +== Overview + +// 1-2 sentences: what this procedure accomplishes and who it is for. +// TODO: verify with engineering + +== Before you begin + +// Prerequisites as a list. Use "You must" or "You need" for each. +* +* + +== Procedure + +. Step one. Include the exact command or UI action. ++ +[source,bash] +---- +# example command here +---- + +. Step two. + +. Step three. + +== Result + +// What the user should see or be able to do after completing the procedure. + +== Next steps + +// Optional. Link to related procedures or concepts. + +== Related information + +* xref::/page.adoc[Link text] diff --git a/modules/_templates/reference.adoc b/modules/_templates/reference.adoc new file mode 100644 index 000000000..0a68ee866 --- /dev/null +++ b/modules/_templates/reference.adoc @@ -0,0 +1,36 @@ += +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: reference +:page-role: +:product-version: +:jira-ref: +// author: +// last-reviewed: + +// Brief description of what this reference covers. + +[cols="1,1,1,3", options="header"] +|=== +|Parameter |Type |Required |Description + +|`param_name` +|string +|Yes +|Description of what this parameter does. Default: none. + +|=== + +== Example + +[source,json] +---- +{ + "param_name": "value" +} +---- + +== Related information + +* xref::/page.adoc[Link text] diff --git a/modules/_templates/release-notes.adoc b/modules/_templates/release-notes.adoc new file mode 100644 index 000000000..1f2366142 --- /dev/null +++ b/modules/_templates/release-notes.adoc @@ -0,0 +1,29 @@ += Release Notes: +:page-type: release-note +:page-role: +:product-version: +:jira-ref: + +== New features + +=== + +// One sentence describing what it does and who benefits. +// TODO: link to full feature documentation once published. + +== Improvements + +* Brief description. () + +== Bug fixes + +* Brief description of what was broken and what was fixed. () + +== Known issues + +* Description of the issue and any workaround. + +== Upgrade notes + +// Required only if this version includes breaking changes or migration steps. +// TODO: verify with engineering \ No newline at end of file From 8a847ab72ff396bf3c25d1fcf850d6e681b1a423 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya Date: Wed, 13 May 2026 23:43:20 +0530 Subject: [PATCH 2/5] edits --- modules/_templates/concept.adoc | 107 +++++++++++++-- modules/_templates/procedure.adoc | 133 +++++++++++++++++-- modules/_templates/reference.adoc | 183 ++++++++++++++++++++++++-- modules/_templates/release-notes.adoc | 111 ++++++++++++++-- 4 files changed, 490 insertions(+), 44 deletions(-) diff --git a/modules/_templates/concept.adoc b/modules/_templates/concept.adoc index 9ed7514fc..d21cac891 100644 --- a/modules/_templates/concept.adoc +++ b/modules/_templates/concept.adoc @@ -1,32 +1,121 @@ = :toc: true :toclevels: 1 -:page-pageid: + +:page-title: +:page-description: <One sentence: what this page covers and why it matters to the reader.> +:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.> +:keywords: <comma-separated terms for search indexing, e.g. "authentication, SSO, SAML, login"> :page-type: concept :page-role: :product-version: <version> :jira-ref: <DOC-XXXX> + // author: // last-reviewed: -// 1-2 sentence lead: what this concept is and why it matters. +// REQUIRED: 1-2 sentence lead — what this concept is and why it matters to developers or administrators. + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/concept.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "embed-sso-overview.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that explain WHAT something is or HOW it works. +Do NOT include step-by-step instructions here — link to a procedure page instead. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Style elements you can use: + Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION] + Images : image::<path>[alt text] + Tables : [cols="...", options="header"] |=== ... |=== + Code blocks : [source,JavaScript] ---- ... ---- + Inline badge : [beta betaBackground]^Beta^ + Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# + [.version-badge.breaking]#Breaking# [.version-badge.fixed]#Fixed# +//// == How <concept> works -// Explanation. Use diagrams (image::) where spatial relationships matter. -// Avoid procedure steps here — link to procedure pages instead. +// REQUIRED. +// Explain the concept clearly. Avoid procedure steps — link to procedure pages instead. +// Use plain language; define acronyms on first use. +// +// Add a diagram or screenshot if spatial relationships or architecture matter: +// image::./images/<diagram-filename>.png[Alt text describing the diagram] +// +// Example: +// image::./images/embed-architecture.png[ThoughtSpot embedded architecture overview showing the SDK, REST API, and host application layers] +// +// Use admonitions to highlight key information: +// [NOTE] +// ==== +// Text for a general note or clarification. +// ==== +// +// [IMPORTANT] +// ==== +// Text for a critical constraint the reader must know before using this feature. +// ==== == Key components -// Optional. Use a definition list for named parts: -Component name:: +// OPTIONAL. +// Use a definition list for named parts or actors in the system: + +Component A:: +Description of what it does and its role in the system. + +Component B:: Description of what it does. +// OPTIONAL: Add a comparison matrix when the concept involves multiple options or variants +// that readers commonly need to choose between: +// +// [cols="1,1,1,1", options="header"] +// |=== +// |Option |Best for |Authentication |Notes +// |REST API v2 |New integrations |Bearer token |Recommended +// |REST API v1 |Legacy systems |Basic auth |Migrate to v2 when possible +// |Visual Embed SDK |Embedded UI |Trusted auth |TypeScript support +// |=== + == Limitations and constraints -// Known limitations, version-specific behaviour, or edge cases. -// TODO: verify with engineering +// RECOMMENDED. +// List known limitations, version-specific behaviour, or edge cases the reader should know. +// Use admonitions for critical constraints: +// +// [IMPORTANT] +// ==== +// This feature requires ThoughtSpot Cloud <version> or later. +// ==== +// +// [NOTE] +// ==== +// Behaviour changed in <version>. If you are on an earlier version, see xref:...[] +// ==== +// +// [WARNING] +// ==== +// Enabling this setting affects all users in the org. Confirm with your administrator before proceeding. +// ==== + +* == Related information -* xref:<component>:<module>/page.adoc[Link text] +// REQUIRED. +// Link to related concept, procedure, and reference pages. +// "Related information" is the standard heading — do not use "Additional resources" or "See also". + +* xref:<module>/page.adoc[Link text] diff --git a/modules/_templates/procedure.adoc b/modules/_templates/procedure.adoc index 11a91ab2c..597a571b2 100644 --- a/modules/_templates/procedure.adoc +++ b/modules/_templates/procedure.adoc @@ -1,46 +1,151 @@ = <Title: Verb + Object, e.g. "Configure Single Sign-On"> :toc: true :toclevels: 1 -:page-pageid: + +:page-title: <Title — must match the = Title above> +:page-description: <One sentence: what this procedure does and who it is for.> +:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.> :page-type: procedure +:keywords: <comma-separated terms for search indexing, e.g. "configure, SSO, SAML, setup"> :page-role: :product-version: <version> :jira-ref: <DOC-XXXX> // author: // last-reviewed: +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/procedure.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "configure-saml-sso.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that describe HOW TO DO something — a sequence of steps +the reader must follow to achieve a specific outcome. +Do NOT explain background theory here — link to a concept page for that. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Code samples: + SDK procedures : JavaScript or TypeScript code sample is REQUIRED. + REST API procedures: cURL code sample is REQUIRED. JSON request/response is REQUIRED. + UI-only procedures : screenshots are RECOMMENDED (use image:: after the relevant step). + +Style elements you can use: + Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION] + Images : image::<path>[alt text] + Code blocks : [source,JavaScript] / [source,TypeScript] / [source,cURL] / [source,JSON] + Inline badge : [beta betaBackground]^Beta^ + Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# + [.version-badge.breaking]#Breaking# +//// + == Overview -// 1-2 sentences: what this procedure accomplishes and who it is for. -// TODO: verify with engineering +// REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for. +// Mention the product area and the role of the reader (developer, administrator, etc.). +// TODO: verify scope with engineering +// +// OPTIONAL: Add a workflow diagram or screenshot of the starting UI state if it helps +// the reader orient themselves before starting: +// image::./images/<workflow-diagram>.png[Workflow overview diagram] == Before you begin -// Prerequisites as a list. Use "You must" or "You need" for each. -* -* +// REQUIRED if there are prerequisites. Use "You must" or "You need" for each item. +// Remove this section only if there are genuinely no prerequisites. + +* You must have <role or permission, e.g. "Developer or Administrator privilege">. +* You need access to <system or resource, e.g. "a ThoughtSpot Cloud instance with the Embed feature enabled">. +* <Any additional prerequisite.> == Procedure -. Step one. Include the exact command or UI action. +// REQUIRED. Use numbered steps. Each step must describe exactly one action. +// Include the exact command, UI label, menu path, or code for each step. +// Add a `+` continuation after a step to attach a code block or image to it. + +. Step one. Describe the exact UI action or navigation path. ++ +// OPTIONAL: Screenshot showing the UI state after this step: +// image::./images/<step1-screenshot>.png[Description of what to see after step 1] + +. Step two. For SDK procedures, provide a complete, runnable code sample — REQUIRED. + -[source,bash] +[source,JavaScript] ---- -# example command here +import { LiveboardEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk'; + +init({ + thoughtSpotHost: 'https://<your-instance>.thoughtspot.cloud', + authType: AuthType.TrustedAuthToken, + username: '<username>', + getAuthToken: () => getTokenFromYourServer(), +}); + +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '<liveboard-GUID>', +}); +embed.render(); ---- ++ +[NOTE] +==== +Replace `<your-instance>` with your ThoughtSpot Cloud hostname and `<liveboard-GUID>` with the ID of the Liveboard you want to embed. +==== -. Step two. +. Step three. For REST API procedures, provide a cURL request — REQUIRED. ++ +[source,cURL] +---- +curl -X POST \ + 'https://<your-instance>.thoughtspot.cloud/api/rest/2.0/<endpoint>' \ + -H 'Authorization: Bearer <token>' \ + -H 'Content-Type: application/json' \ + -d '{ + "param": "value" + }' +---- ++ +// OPTIONAL: Show the expected JSON response inline: +// [source,JSON] +// ---- +// { +// "field": "value" +// } +// ---- -. Step three. +// OPTIONAL: Add a WARNING or NOTE for common pitfalls at the end of the procedure. +// [WARNING] +// ==== +// If you see <error>, verify that <condition> before retrying. +// ==== == Result -// What the user should see or be able to do after completing the procedure. +// REQUIRED. Describe what the user should see or be able to do after completing the procedure. +// Be specific — name the UI element, API response, or behaviour that confirms success. +// +// OPTIONAL: Screenshot of the expected result: +// image::./images/<result-screenshot>.png[Expected result after completing the procedure] == Next steps -// Optional. Link to related procedures or concepts. +// OPTIONAL. Link to the next logical task or a related procedure. + +* xref:<module>/next-procedure.adoc[Next task name] == Related information -* xref:<component>:<module>/page.adoc[Link text] +// REQUIRED. +// Link to related concept and reference pages. +// "Related information" is the standard heading — do not use "Additional resources" or "See also". + +* xref:<module>/concept-page.adoc[Related concept] +* xref:<module>/reference-page.adoc[API reference] diff --git a/modules/_templates/reference.adoc b/modules/_templates/reference.adoc index 0a68ee866..8dfdec29c 100644 --- a/modules/_templates/reference.adoc +++ b/modules/_templates/reference.adoc @@ -1,15 +1,96 @@ -= <Title: Noun phrase, e.g. "API Endpoint Reference"> += <Title: Noun phrase, e.g. "Liveboard report API reference"> :toc: true -:toclevels: 1 +:toclevels: 1 <-- adjust if you have many sections, but 1-2 levels is usually sufficient for reference pages> + +:page-title: <Title — must match the = Title above> +:page-description: <One sentence: what this reference documents and who uses it.> +:keywords: <comma-separated terms for search indexing, e.g. "REST API, parameters, endpoints, reference"> :page-pageid: :page-type: reference :page-role: :product-version: <version> :jira-ref: <DOC-XXXX> // author: -// last-reviewed: +// last-updated: + +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/reference.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "rest-api-auth-reference.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. + +Use this template for pages that document parameters, properties, endpoints, request /response worklows, classes, enumerations, or configuration options — reference material a reader looks up, not reads start-to-finish. + +Section labels: + REQUIRED — must be present on every page of this type + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to the topic + +Code samples: + SDK reference : JavaScript or TypeScript example is REQUIRED. + REST API reference : cURL request + JSON response are REQUIRED. + Resource URL, Request parameters, Example request, + Example response, and Response codes are all REQUIRED + for each endpoint documented on this page. + +Style elements you can use: + Tables : [cols="...", options="header"] |=== ... |=== + Code blocks : [source,JavaScript] / [source,TypeScript] / [source,cURL] / [source,JSON] + Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING] + Inline badge : [beta betaBackground]^Beta^, [earlyAccess eaBackground]#Early Access# + Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# + [.version-badge.breaking]#Breaking# +//// + +// REQUIRED: 1-2 sentences describing what this reference covers — the API, SDK class, +// endpoint group, or configuration object — and the primary use case. + +// OPTIONAL: Comparison matrix — use when documenting multiple methods, endpoints, or +// authentication options that readers commonly need to choose between: +// +// [cols="1,1,1,1", options="header"] +// |=== +// |Method |Auth type |Rate limit |Notes +// |REST API v2 |Bearer token |1000/min |Recommended for new integrations +// |REST API v1 |Basic auth |500/min |Legacy; migrate to v2 when possible +// |Visual Embed SDK |Trusted auth |N/A |TypeScript support; browser only +// |=== + +== Supported operations + +// OPTIONAL for REST API reference pages that cover multiple endpoints. +// List the endpoints or operations covered on this page. +// Use an include directive if the list is generated: +// include::{path}/<api>-list.adoc[] + +=== Required permissions + +// RECOMMENDED: State the role or permission required to call these APIs. -// Brief description of what this reference covers. + +// ───────────────────────────────────────────────────────────────────────────── +// ENDPOINT / ATTRIBUTE BLOCK +// Repeat this block for each endpoint or configuration property. +// ───────────────────────────────────────────────────────────────────────────── + +== <Operation or property name> + +// REQUIRED: One sentence describing what this endpoint or property does. + +=== Resource URL + +// REQUIRED for REST API reference. Use a literal block (no syntax highlighting). +---- +POST /api/rest/2.0/<endpoint-path> +---- + +=== Request parameters + +// REQUIRED. Document every parameter. Use "None" if there are no parameters. [cols="1,1,1,3", options="header"] |=== @@ -20,17 +101,103 @@ |Yes |Description of what this parameter does. Default: none. +|`optional_param` +|boolean +|No +|Optional flag. Default: `false`. + |=== -== Example +// OPTIONAL: Version-specific notes — use inline badges to flag changes per parameter: +// [.version-badge.new]#New in vX.X# `new_param` — added in this version; description. +// [.version-badge.deprecated]#Deprecated# `old_param` — deprecated in vX.X; use `new_param` instead. +// [.version-badge.breaking]#Breaking# `changed_param` — behaviour changed in vX.X. + +=== Example request + +// REQUIRED. Provide a complete, working example. +// For SDK reference: -[source,json] +[source,JavaScript] +---- +import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk'; + +const embed = new LiveboardEmbed('#embed-container', { + liveboardId: '<liveboard-GUID>', + // Optional parameters: + fullHeight: true, + disabledActions: [], +}); +embed.render(); +---- + +// For REST API reference — provide a cURL example: + +[source,cURL] +---- +curl -X POST \ + 'https://<your-instance>.thoughtspot.cloud/api/rest/2.0/<endpoint>' \ + -H 'Authorization: Bearer <token>' \ + -H 'Content-Type: application/json' \ + -d '{ + "param_name": "value", + "optional_param": false + }' +---- + +=== Example response + +// REQUIRED for REST API reference. + +[source,JSON] ---- { - "param_name": "value" + "field": "value", + "nested": { + "key": "value" + } } ---- +=== Response codes + +// REQUIRED for REST API reference. + +[cols="1,1,3", options="header"] +|=== +|Code |Status |Description + +|200 +|Success +|Request completed. Returns the response object described above. + +|400 +|Bad request +|Invalid parameters. Verify required fields and data types. + +|401 +|Unauthorized +|Authentication failed. Check your bearer token or API credentials. + +|403 +|Forbidden +|Insufficient permissions. Verify the user role required for this operation. + +|500 +|Internal server error +|Contact ThoughtSpot Support if the error persists. + +|=== + +// ───────────────────────────────────────────────────────────────────────────── +// END ENDPOINT / ATTRIBUTE BLOCK — copy the block above for additional endpoints +// ───────────────────────────────────────────────────────────────────────────── + == Related information -* xref:<component>:<module>/page.adoc[Link text] +// REQUIRED. +// Link to related how-to and concept pages. +// "Related information" is the standard heading — do not use "Additional resources" or "See also". + +* xref:<module>/procedure-page.adoc[How to <use this API>] +* xref:<module>/concept-page.adoc[Related concept] diff --git a/modules/_templates/release-notes.adoc b/modules/_templates/release-notes.adoc index 1f2366142..a9379d3e0 100644 --- a/modules/_templates/release-notes.adoc +++ b/modules/_templates/release-notes.adoc @@ -1,29 +1,114 @@ -= Release Notes: <Product> <Version> += Release notes: <Product> <Version or Month Year> +:toc: true +:toclevels: 1 +:page-title: <Title — must match the = Title above> +:page-description: <One sentence: summary of what is new or changed in this release.> +:keywords: <comma-separated terms for search indexing, e.g. "release notes, changelog, new features, ThoughtSpot Cloud"> :page-type: release-note :page-role: :product-version: <version> :jira-ref: <DOC-XXXX> -== New features +//// +TEMPLATE GUIDE +============== +How to use this template: + 1. Copy this file from modules/_templates/release-notes.adoc. + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "release-notes-26-5.adoc"). + 3. Place the file in modules/ROOT/pages/. + 4. If this page will be included as a partial inside another page (via include::), + remove all front-matter attributes — partials do not need them. -=== <Feature name> +Use this template for release note pages (What's New, changelogs, version history). +Base format: tabular layout modelled on the existing What's New and changelog pages. -// One sentence describing what it does and who benefits. -// TODO: link to full feature documentation once published. +Section labels: + REQUIRED — must be present on every release note page + RECOMMENDED — include unless there is a clear reason not to + OPTIONAL — include only when relevant to this release -== Improvements +Tags (column cell — use in the first column of the change table): + [tag greenBackground]#NEW FEATURE# + [tag greenBackground]#IMPROVEMENT# + [tag redBackground]#DEPRECATED# + [tag redBackground]#BUG FIX# -* Brief description. (<JIRA-REF>) +Inline badges (append after a feature name or inside a description): + [beta betaBackground]^Beta^ — feature is in Beta + [.version-badge.new]#New# — new in this version + [.version-badge.breaking]#Breaking# — breaking change + [.version-badge.deprecated]#Deprecated# — item is deprecated + [.version-badge.fixed]#Fixed# — bug fix -== Bug fixes +Format notes: + - Use [discrete] before ==== headings inside table cells to suppress TOC entries. + - Separate entries within the same cell with a horizontal rule: --- + - Each JIRA reference appears in parentheses at the end: (DOC-XXXX) + - Use `*` bold for version labels and metadata lines inside cells. + - Link to full documentation using xref once the target page is published. +//// -* Brief description of what was broken and what was fixed. (<JIRA-REF>) +// REQUIRED: One sentence stating the release scope and any critical headline. +This release includes updates to <product area, e.g. "the Visual Embed SDK and REST API v2.0">. -== Known issues +// REQUIRED: Release metadata block. +**Release version**: ThoughtSpot Cloud <X.X.X.cl> + +*Upgrade notes*: <None. / ⚠️ Describe any breaking changes; link to Upgrade notes section.> + +*Recommended SDK versions*: Visual Embed SDK v<X.XX.X> and later + +// REQUIRED: Change table. +// Each row = one change category. Repeat rows as needed. +// The first column holds the tag; the second holds all entries for that category. + +[width="100%" cols="1,4"] +|==== + +// ── NEW FEATURES ────────────────────────────────────────────────────────────── +|[tag greenBackground]#NEW FEATURE# a| + +[discrete] +==== <Feature name> [beta betaBackground]^Beta^ + +// REQUIRED: One sentence describing what it does and who benefits. +// TODO: replace the placeholder link once the documentation page is published. +// xref:<page>.adoc[<Feature name>] +Description of the new feature and its benefit to developers or administrators. + +--- + +[discrete] +==== <Second new feature name> + +Description of the second new feature. + +// ── IMPROVEMENTS ────────────────────────────────────────────────────────────── +|[tag greenBackground]#IMPROVEMENT# a| -* Description of the issue and any workaround. +* Brief description of the improvement. (DOC-XXXX) +* Brief description of another improvement. (DOC-XXXX) +// ── DEPRECATIONS ────────────────────────────────────────────────────────────── +|[tag redBackground]#DEPRECATED# a| + +* `<deprecated_item>` — deprecated in this release. Use `<replacement>` instead. (DOC-XXXX) + +// ── BUG FIXES ───────────────────────────────────────────────────────────────── +|[tag redBackground]#BUG FIX# a| + +* Brief description of what was broken and what was fixed. (DOC-XXXX) +* Brief description of another bug fix. (DOC-XXXX) + +|==== + +// REQUIRED only when this release includes breaking changes or migration steps. == Upgrade notes -// Required only if this version includes breaking changes or migration steps. -// TODO: verify with engineering \ No newline at end of file +// Document breaking changes, configuration updates, or migration steps required. +// Reference specific API endpoints, SDK methods, or config keys by name. +// TODO: verify all migration steps with engineering before publishing. + +== Known issues + +// OPTIONAL but recommended. Describe open issues in this release and any workaround. + +* Description of the known issue. Workaround: <steps or link>. (DOC-XXXX) From 4f59ebfe7ad613dd7d1bc0d410e09c9d4892d62b Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <shashikala.subramanya@thoughtspot.com> Date: Wed, 20 May 2026 11:14:22 +0530 Subject: [PATCH 3/5] vale style checks --- .github/workflows/vale.yml | 31 +++ .gitignore | 5 + .vale-ci.ini | 22 ++ .vale.ini | 137 +++++++++++ .../config/vocabularies/ts-vocab/accept.txt | 153 ++++++++++++ .../config/vocabularies/ts-vocab/reject.txt | 29 +++ .vale/styles/ts-docs/Abbreviations.yml | 74 ++++++ .vale/styles/ts-docs/Ampersands.yml | 13 + .vale/styles/ts-docs/AsciiDocSyntax.yml | 53 ++++ .vale/styles/ts-docs/DoNotUseTerms.yml | 71 ++++++ .vale/styles/ts-docs/Headings.yml | 117 +++++++++ .vale/styles/ts-docs/LinkText.yml | 17 ++ .vale/styles/ts-docs/PreCommitChecks.yml | 54 +++++ .vale/styles/ts-docs/RepeatedWords.yml | 17 ++ .vale/styles/ts-docs/SentenceLength.yml | 11 + .vale/styles/ts-docs/SmartQuotes.yml | 16 ++ .vale/styles/ts-docs/WordList.yml | 212 ++++++++++++++++ .valeignore | 24 ++ modules/ROOT/pages/authentication.adoc | 6 +- modules/ROOT/pages/variables.adoc | 1 + modules/_templates/best-practices.adoc | 79 ++++++ modules/_templates/concept.adoc | 12 +- modules/_templates/faqs.adoc | 64 +++++ modules/_templates/procedure.adoc | 14 +- modules/_templates/quickstart.adoc | 113 +++++++++ modules/_templates/reference.adoc | 13 +- modules/_templates/release-notes.adoc | 8 +- modules/_templates/troubleshooting.adoc | 90 +++++++ modules/_templates/tutorial.adoc | 229 ++++++++++++++++++ 29 files changed, 1659 insertions(+), 26 deletions(-) create mode 100644 .github/workflows/vale.yml create mode 100644 .vale-ci.ini create mode 100644 .vale.ini create mode 100644 .vale/styles/config/vocabularies/ts-vocab/accept.txt create mode 100644 .vale/styles/config/vocabularies/ts-vocab/reject.txt create mode 100644 .vale/styles/ts-docs/Abbreviations.yml create mode 100644 .vale/styles/ts-docs/Ampersands.yml create mode 100644 .vale/styles/ts-docs/AsciiDocSyntax.yml create mode 100644 .vale/styles/ts-docs/DoNotUseTerms.yml create mode 100644 .vale/styles/ts-docs/Headings.yml create mode 100644 .vale/styles/ts-docs/LinkText.yml create mode 100644 .vale/styles/ts-docs/PreCommitChecks.yml create mode 100644 .vale/styles/ts-docs/RepeatedWords.yml create mode 100644 .vale/styles/ts-docs/SentenceLength.yml create mode 100644 .vale/styles/ts-docs/SmartQuotes.yml create mode 100644 .vale/styles/ts-docs/WordList.yml create mode 100644 .valeignore create mode 100644 modules/_templates/best-practices.adoc create mode 100644 modules/_templates/faqs.adoc create mode 100644 modules/_templates/quickstart.adoc create mode 100644 modules/_templates/troubleshooting.adoc create mode 100644 modules/_templates/tutorial.adoc diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..b469a474d --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,31 @@ +name: Vale + +on: + pull_request: + branches: + - main + - release + +jobs: + vale: + name: Lint prose (ts-docs) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run Vale + uses: errata-ai/vale-action@v2 + with: + # CI config: ts-docs rules only, error level gate. + # Does not run vale sync — no package downloads needed. + config: .vale-ci.ini + # Check only files changed in this PR. + files: changed + # Fail the build on errors (merge conflict markers, + # unfilled placeholders). Warnings are reported but + # do not block the PR. + fail_on_error: true + reporter: github-pr-review + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.gitignore b/.gitignore index d07bcc884..5dc82b830 100644 --- a/.gitignore +++ b/.gitignore @@ -106,6 +106,11 @@ docs/public/ # TernJS port file .tern-port +# Vale prose linter — downloaded packages (committed: ts-docs style + ts-vocab) +# Run `vale sync` after cloning to download these. +.vale/styles/Google/ +.vale/styles/Microsoft/ + # Code editors or IDEs .vscode/ diff --git a/.vale-ci.ini b/.vale-ci.ini new file mode 100644 index 000000000..15c17fbb5 --- /dev/null +++ b/.vale-ci.ini @@ -0,0 +1,22 @@ +# ============================================================= +# .vale-ci.ini — CI-only Vale configuration +# ============================================================= +# Used exclusively by the GitHub Actions vale.yml workflow. +# Runs only the committed ts-docs style; does NOT require +# `vale sync` (no Google / Microsoft packages are downloaded). +# +# Gate: MinAlertLevel = error — only hard errors fail the build. +# ts-docs rules at error level: +# - PreCommitChecks (merge conflict markers, unfilled placeholders) +# ============================================================= + +StylesPath = .vale/styles +MinAlertLevel = error +Vocab = ts-vocab + +[*.{adoc,asciidoc}] +BasedOnStyles = ts-docs + +# Preserve the same AsciiDoc comment and inline-span exclusions as .vale.ini +TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\]) +BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4}) diff --git a/.vale.ini b/.vale.ini new file mode 100644 index 000000000..b0d8d04c0 --- /dev/null +++ b/.vale.ini @@ -0,0 +1,137 @@ +# ============================================================= +# .vale.ini — ThoughtSpot Developer Docs +# ============================================================= +# SETUP (one-time, after cloning): +# vale sync +# This downloads Google and Microsoft into .vale/styles/ (gitignored). +# The ts-docs custom style and ts-vocab vocabulary are committed to the repo. +# +# USAGE: +# vale path/to/file.adoc +# vale modules/ROOT/pages/ +# +# INTELLIJ IDEA: +# Settings > Tools > Vale > Config: point to this file. +# The AsciiDoc plugin picks up Vale alerts inline. +# ============================================================= + +StylesPath = .vale/styles + +# suggestion = show everything (noisy, good for authoring) +# warning = hide suggestions, show warnings + errors (recommended for review) +# error = show only blocking errors (good for CI gates) +MinAlertLevel = suggestion + +# ---- Packages (downloaded by `vale sync`, then gitignored) -- +Packages = Google, Microsoft + +# ---- Shared vocabulary -------------------------------------- +# Files: .vale/styles/config/vocabularies/ts-vocab/accept.txt +# reject.txt +Vocab = ts-vocab + +# ============================================================= +# Catch-all: disable Vale on every file type not listed below. +# This prevents IDE plugins from running checks on .yml, .json, +# .js, and other non-prose files even when .valeignore is ignored. +# ============================================================= +[*] +BasedOnStyles = + +# ============================================================= +# AsciiDoc files (authored content only) +# Generated pages and node_modules are excluded via .valeignore +# ============================================================= +[*.{adoc,asciidoc}] +BasedOnStyles = Google, Microsoft, ts-docs + +# ---- Comment exclusions ------------------------------------- +# AsciiDoc single-line comments (// text) are ignored. +# AsciiDoc block comments (////...////) are ignored. +# EXCEPTION: comments inside ---- code blocks are part of code +# content and are preserved by Asciidoctor — they are not +# matched by these patterns and continue to be checked. +# Inline role spans are also stripped before style rules run so that +# capitalization checks do not fire on fixed labels: +# [.version-badge.*]#New# [.version-badge.*]#Breaking# +# [tag *]#NEW FEATURE# [tag *]#DEPRECATED# +# [earlyAccess *]#Early Access# [beta *]^Beta^ +# [NOTE] [WARNING] [IMPORTANT] [TIP] [CAUTION] +TokenIgnores = (\/\/.+), (\[(?:\.version-badge[^\]]*|tag [^\]]*|earlyAccess [^\]]*|beta [^\]]*)\][#^][^#^]+[#^]), (\[(NOTE|TIP|WARNING|IMPORTANT|CAUTION|DANGER)\]) +BlockIgnores = (?s)(\/{4}[\s\S]*?\/{4}) + +# ---- Rule overrides ----------------------------------------- +# Tuned based on audit of alerts against ThoughtSpot developer docs. + +# Vocabulary: managed by ts-vocab; disable built-in Microsoft vocab. +Microsoft.Vocab = NO + +# Headings: sentence case enforced by ts-docs.Headings. +Google.Headings = NO +Microsoft.Headings = NO +Microsoft.HeadingPunctuation = NO +Microsoft.HeadingAcronyms = NO + +# Passive voice: sometimes necessary in reference docs. +Microsoft.Passive = NO +Google.Passive = suggestion + +# Contractions: avoid in formal developer docs. +Microsoft.Contractions = NO + +# List-item punctuation: technical lists often don't end with periods. +Microsoft.Periods = NO + +# Oxford comma: required. +Google.OxfordComma = error + +# URLs: Antora/AsciiDoc handles link formatting; these rules add noise. +Microsoft.GeneralURL = NO +Microsoft.URLFormat = NO + +# Sentence length: covered by ts-docs.SentenceLength. +Microsoft.SentenceLength = NO + +# Parentheses and optional plurals: too noisy for technical API docs. +Google.Parens = NO +Google.OptionalPlurals = NO + +# Google WordList: contains Google-internal product name substitutions +# (for example, Cloud → "Google Cloud Platform") that conflict with +# ThoughtSpot product names. Applicable entries are maintained in +# ts-docs/WordList.yml instead. +Google.WordList = NO + +# Date format: downgraded from error — docs use various date formats +# depending on context (API responses, UI labels, prose). +Microsoft.DateFormat = suggestion +Google.DateFormat = suggestion + +# Colon capitalisation: flags proper nouns and product names after colons. +# Cannot be tuned without rewriting the rule. +Google.Colons = NO +Microsoft.HeadingColons = NO + +# Semicolons: "Use semicolons judiciously" is not actionable feedback. +Google.Semicolons = NO +Microsoft.Semicolon = NO + +# Dotted abbreviations: error-level rule flagging U.S.A.-style patterns. +# Writers are aware of this convention; same check was intentionally +# excluded from ts-docs styles. +Google.Periods = NO + +# Avoided terms: relevant token (and so on) absorbed into ts-docs.DoNotUseTerms. +# Remaining tokens are Microsoft-specific or legitimate in ThoughtSpot docs. +Microsoft.Avoid = NO + +# Wordy phrases: applicable substitutions absorbed into ts-docs.WordList. +# Rule suppressed to avoid duplicate alerts. +Microsoft.Wordiness = NO + +# ============================================================= +# Markdown files +# ============================================================= +[*.{md,markdown}] +BasedOnStyles = Google, Microsoft, ts-docs + diff --git a/.vale/styles/config/vocabularies/ts-vocab/accept.txt b/.vale/styles/config/vocabularies/ts-vocab/accept.txt new file mode 100644 index 000000000..9d49499c0 --- /dev/null +++ b/.vale/styles/config/vocabularies/ts-vocab/accept.txt @@ -0,0 +1,153 @@ +# ts-vocab/accept.txt +# Terms Vale's spell-check should accept as correctly spelled. +# One entry per line. Regex is supported. +# Add product names, SDK identifiers, and technical terms here +# rather than suppressing spell-check globally. + +# ------------------------------------------------------- +# THOUGHTSPOT PRODUCT AND PLATFORM NAMES +# Prose form - correctly capitalised brand name +# ------------------------------------------------------- +ThoughtSpot +ThoughtSpot Cloud +ThoughtSpot Embedded +Visual Embed SDK +REST API v2 +REST API Playground +ThoughtSpotSDK +ThoughtSpotRestApi +ThoughtSpotDeliveryRole + +# ------------------------------------------------------- +# THOUGHTSPOT LOWERCASE / CODE-CONTEXT VARIANTS +# These appear legitimately in URLs, config parameters, +# variable names, and code - accepted here so the spell +# checker does not flag them. +# ------------------------------------------------------- +thoughtspot +thoughtSpotHost +thoughtSpotUrl +thoughtspot\.cloud +tsconfig +tsEmbedSDK + +# ------------------------------------------------------- +# SPOTTER / AI PRODUCT NAMES +# ------------------------------------------------------- +Spotter +SpotterAgent +SpotterCode +SpotterDocs +SpotterEmbed +SpotterAgentEmbed +SpotterAgentEmbedConfig +SpotterAgentEmbedViewConfig +SpotterChatConnectors +SpotterChatConnectorResources +SpotterChatDelete +SpotterChatMenu +SpotterChatModeSwitcher +SpotterChatRename +SpotterChatViewConfig +SpotterConversationDeleted +SpotterConversationRenamed +SpotterConversationSelected +SpotterCSS +SpotterEmbedViewConfig +SpotterFeedback +SpotterInit +SpotterMessage +SpotterNewChat +SpotterPastChatBanner +SpotterQueryTriggered +SpotterSearch +SpotterSidebarFooter +SpotterSidebarHeader +SpotterSidebarToggle +SpotterSidebarViewConfig +SpotterTokenQuickEdit +SpotterWarningsBanner +SpotterWarningsOnTokens +ConversationEmbed + +# ------------------------------------------------------- +# EMBED SDK COMPONENT NAMES +# ------------------------------------------------------- +AppEmbed +LiveboardEmbed +LiveboardEmbedController +LiveboardEmbedView +SearchEmbed +SearchBarEmbed +SpotterAgentEmbed +PreRenderedLiveboardEmbed +TsEmbedSDK +SwiftEmbedSDK +TSEmbedConfig +EmbedConfig +visual-embed-sdk + +# ------------------------------------------------------- +# LIVEBOARD AND DATA TYPES +# ------------------------------------------------------- +Liveboard +Liveboards +LiveboardActionData +LiveboardConfigStyle +LiveboardContextActionData +LiveboardController +LiveboardData +LiveboardInfo +LiveboardPureStyle +LiveboardRendered +LiveboardScheduleData +LiveboardSchedules +LiveboardStyle +LiveboardStyleConfig +LiveboardStylePanel +LiveboardUsers +LiveboardView +LiveboardViewConfig + +# ------------------------------------------------------- +# AUTH AND CONFIG TYPES +# ------------------------------------------------------- +AuthType +TrustedAuthToken +TrustedAuthTokenCookieless +TrustedAuthCookieless +EmbedEvent +HostEvent +RuntimeFilter +RuntimeSort +OAuthRedirectWindowType +ConnectionType + +# ------------------------------------------------------- +# PLATFORM AND FEATURE TERMS +# ------------------------------------------------------- +SpotApps +SpotDev +spotdev +TML +GUID +Antora +TSCLI +tscli + +# Worksheet is deprecated in prose (WordList.yml flags it). +# Retained here so the spell checker does not flag the term +# in code blocks or SDK parameter contexts (e.g. worksheetId). +Worksheet +Worksheets +worksheetId +worksheetIds + +# ------------------------------------------------------- +# INTEGRATION AND CLOUD +# ------------------------------------------------------- +Snowflake +Databricks +Salesforce +Vercel +Pendo diff --git a/.vale/styles/config/vocabularies/ts-vocab/reject.txt b/.vale/styles/config/vocabularies/ts-vocab/reject.txt new file mode 100644 index 000000000..0b2a6e00f --- /dev/null +++ b/.vale/styles/config/vocabularies/ts-vocab/reject.txt @@ -0,0 +1,29 @@ +# ts-vocab/reject.txt +# Plain English terms that are wrong in ALL contexts (prose, headings). +# Vale flags any match as a spelling error. +# One entry per line. Regex is supported. +# +# SCOPE NOTE: reject.txt runs through the spell checker. +# Code blocks are excluded by Vale's Asciidoctor parser, but +# inline code and attribute values may still be checked. +# For deprecated SDK class names, use WordList.yml (tokens:) +# which is strictly prose-scoped. +# +# Use this file only for plain English words that are ALWAYS +# wrong in authored prose, regardless of context. + +# ------------------------------------------------------- +# DEPRECATED PRODUCT / FEATURE NAMES +# "pinboard" and "pinboards" are plain English words that +# should always be replaced with Liveboard in prose. +# Word boundaries prevent matching PinboardEmbed etc. +# ------------------------------------------------------- +\bpinboard\b +\bpinboards\b +\bPinboard\b +\bPinboards\b + +# ------------------------------------------------------- +# ADD DEPRECATED OR BANNED TERMS BELOW +# ------------------------------------------------------- +# OldProductName diff --git a/.vale/styles/ts-docs/Abbreviations.yml b/.vale/styles/ts-docs/Abbreviations.yml new file mode 100644 index 000000000..ee7753ea4 --- /dev/null +++ b/.vale/styles/ts-docs/Abbreviations.yml @@ -0,0 +1,74 @@ +# ts-docs/Abbreviations.yml +# Flags acronyms used without a definition earlier on the same page. +# Expected format on first use: Full Name (ACRONYM) +# Example: "Representational State Transfer (REST)" +# +# How it works: +# For each bare acronym (first pattern), Vale checks whether the +# spelled-out form with the acronym in parentheses (second pattern) +# has appeared before it in the document. If not, it flags that use. +# Once a definition is added, all subsequent bare uses are cleared. +# scope: text means the entire file is the unit of comparison. +extends: conditional +message: "Define '%s' on first use: spell it out as 'Full Name (ABBR)'." +level: warning +ignorecase: false +# Bare acronym - three or more consecutive uppercase letters, optional plural s +first: '\b([A-Z]{3,}s?)\b' +# Spelled-out form followed by the acronym in parentheses +# e.g. "Representational State Transfer (REST)" +second: '(?:[A-Za-z][A-Za-z]* ){1,}\(([A-Z]{3,})\)' +scope: text + +exceptions: + # Include well-known acronyms and abbreviations that need not be defined in technical documentation + # If the documentation is intended for non-technical audience, define these on first use + # Add THOUGHTSPOT and product-specific acronyms/abbreviations that need not be expanded/defined. + - AI + - API + - APIs + - AWS + - BI + - CD + - CDN + - CI + - CLI + - CSS + - CSV + - DOM + - ETL + - FAQ + - GA + - GCP + - GUID + - HTML + - HTTP + - HTTPS + - IDE + - JSON + - JWT + - LLM + - MFA + - OAuth + - PDF + - PNG + - REST + - SAML + - SDK + - SQL + - SSH + - SSL + - SpotIQ + - SSO + - TLS + - URI + - URL + - URLs + - UI + - UX + - XLSX + - XML + - YAML + + # Add acronyms below + # - XYZ diff --git a/.vale/styles/ts-docs/Ampersands.yml b/.vale/styles/ts-docs/Ampersands.yml new file mode 100644 index 000000000..e9a606b9f --- /dev/null +++ b/.vale/styles/ts-docs/Ampersands.yml @@ -0,0 +1,13 @@ +# ts-docs/Ampersands.yml +# Flags ampersands used in place of "and" in prose. +# ThoughtSpot style: spell out "and" in full. +# Exception: ampersands are allowed in formal names and +# common abbreviations (Q&A, R&D, P&L) where no spaces +# surround the symbol - those forms are not matched here. +extends: existence +message: "Spell out 'and' in full. Use '&' only in formal names (e.g. Q&A, R&D)." +level: warning +tokens: + # Matches & surrounded by spaces - the prose "and" usage. + # Does NOT match Q&A, R&D, or other no-space abbreviations. + - '\s&\s' diff --git a/.vale/styles/ts-docs/AsciiDocSyntax.yml b/.vale/styles/ts-docs/AsciiDocSyntax.yml new file mode 100644 index 000000000..698a46446 --- /dev/null +++ b/.vale/styles/ts-docs/AsciiDocSyntax.yml @@ -0,0 +1,53 @@ +# ts-docs/AsciiDocSyntax.yml +# Flags AsciiDoc markup and convention issues that cause rendering +# problems in Antora or break accessibility and link integrity. +# All patterns run on raw source text before Vale strips markup. +# +# Checks: +# - Unresolved attribute references {attr-name} +# - Bare or malformed URL macros +# - Missing blank line before list items +# - Source blocks without a language tag +# - Image macros with empty alt text (accessibility) +# - Xref and hyperlink convention violations (Antora) +extends: existence +message: "AsciiDoc markup or convention issue: '%s'. Check formatting." +level: warning +raw: + # ---- Attribute references -------------------------------- + # Unresolved attribute references (common in Antora content). + # Matches {attr-name} that is NOT followed by a + continuation. + - '\{[a-z][a-z0-9-]+\}(?!\+)' + + # ---- URL macros ------------------------------------------ + # Bare URLs without a link macro - render literally in some outputs. + # Matches http(s)://... followed by an unclosed bracket. + - 'https?://\S+\[(?!\])' + + # ---- List formatting ------------------------------------- + # Missing blank line before a list item - common cause of list + # items rendering as plain text instead of a list. + - '^[*-]\s' + + # ---- Source blocks --------------------------------------- + # Source block without a language tag produces unhighlighted output. + # Use [source,language], e.g. [source,javascript] or [source,bash]. + - '^\[source\]$' + - '^\[source,\s*\]$' + + # ---- Image alt text (accessibility) ---------------------- + # Image macros with empty alt text break screen readers (WCAG 2.1 AA). + # FAIL: image::diagram.png[] PASS: image::diagram.png[API flow diagram] + # FAIL: image:icon.png[] PASS: image:icon.png[Settings icon] + - 'image::[^\[]+\[\s*\]' + - 'image:[^:][^\[]+\[\s*\]' + + # ---- Xref and hyperlink conventions (Antora) ------------- + # Double-bracket cross-reference: Antora recommends xref: syntax. + - '<<[a-zA-Z_][^>]*>>' + # xref: macro with empty display text — readers need descriptive text. + - 'xref:[^\[]+\[\s*\]' + # link: macro for an internal .adoc file — use xref: instead. + - 'link:[^\[]*\.adoc\[' + # External link macro with empty display text. + - 'link:https?://[^\[]+\[\s*\]' diff --git a/.vale/styles/ts-docs/DoNotUseTerms.yml b/.vale/styles/ts-docs/DoNotUseTerms.yml new file mode 100644 index 000000000..08e2c3673 --- /dev/null +++ b/.vale/styles/ts-docs/DoNotUseTerms.yml @@ -0,0 +1,71 @@ +# ts-docs/DoNotUseTerms.yml +# Flags phrases and words that add no meaning, violate the ThoughtSpot +# developer docs style guide, or are inappropriate in technical writing. +# Renamed from BannedPhrases.yml; expanded with IBM/RedHat-sourced additions. +extends: existence +message: "Avoid '%s' in technical documentation. Rewrite the sentence." +link: '' +level: warning +ignorecase: true +tokens: + # ---- Filler / hedge words -------------------------------- + - 'simply' + # Excludes "just-in-time" and "just in time" (legitimate technical phrases). + - 'just(?![ -]in[ -]time)' + - '\beasy\b' + - '\beast\b' + - 'easily' + - 'trivial' + - 'obviously' + - 'of course' + - 'clearly' + - 'basically' + - 'essentially' + - 'actually' + - '\bvery\b' + - '\bquite\b' + - '\breally\b' + + # ---- Vague time / marketing language -------------------- + - '\bsoon\b' + - 'new and improved' + - 'state of the art' + - 'cutting[- ]edge' + - 'best in class' + - 'world[- ]class' + - 'industry[- ]leading' + - 'best of breed' + + # ---- Redundant meta-commentary -------------------------- + - 'as mentioned (above|previously|earlier)' + - 'as stated (above|previously|earlier)' + - 'needless to say' + - 'it goes without saying' + - 'it should be noted' + - 'it is important to note' + + # ---- "Please" in technical writing ---------------------- + # Technical docs use imperative voice; "please" is informal. + - '\bplease\b' + + # ---- Ambiguous constructions (IBM/RedHat) --------------- + # and/or: rewrite as "a and b", "a or b", or "a, b, or both". + - 'and/or' + # "respectively" forces readers to mentally match items across lists; + # rewrite as explicit pairings instead. + - '\brespectively\b' + + # ---- Vague enumerations (Microsoft.Avoid) --------------- + # "and so on" is vague — list all items explicitly or use "such as". + - 'and so on' + + # ---- Placeholder jargon --------------------------------- + # foo/fubar are developer in-jokes; use descriptive variable names. + - '\bfoo\b' + - '\bfubar\b' + + # ---- ThoughtSpot-specific banned phrases ---------------- + # Add deprecated product names, old slogans, or phrases + # prohibited by legal or brand guidelines. + # - 'OldBrandName' + # - 'deprecated-feature' diff --git a/.vale/styles/ts-docs/Headings.yml b/.vale/styles/ts-docs/Headings.yml new file mode 100644 index 000000000..fcda57cf0 --- /dev/null +++ b/.vale/styles/ts-docs/Headings.yml @@ -0,0 +1,117 @@ +# ts-docs/Headings.yml +# Enforces sentence-case headings (capitalise only the first word +# and proper nouns). Follows Google and Red Hat conventions. +extends: capitalization +message: "'%s' should use sentence case — capitalise only the first word and noun phrases." +level: warning +scope: heading +match: $sentence +# Add every proper noun, product name, acronym, and brand term +# that should remain capitalised mid-heading. +exceptions: + # ------------------------------------------------------- + # STANDARD TECHNICAL ACRONYMS + # ------------------------------------------------------- + - API + - APIs + - CLI + - UI + - UX + - URL + - URLs + - URI + - HTTP + - HTTPS + - REST + - YAML + - JSON + - XML + - HTML + - CSS + - SQL + - SSH + - TLS + - SSL + - OAuth + - JWT + - SDK + - IDE + - CI + - CD + - AWS + - GCP + - Azure + - Linux + - macOS + - Windows + - GitHub + - GitLab + - Docker + - Kubernetes + + # ------------------------------------------------------- + # THOUGHTSPOT PRODUCT AND BRAND NAMES + # ------------------------------------------------------- + - ThoughtSpot + - Spotter + - SpotterAgent + - SpotterCode + - SpotterDocs + - SpotApps + - SpotDev + + # Embed SDK component names + - AppEmbed + - LiveboardEmbed + - SearchEmbed + - SearchBarEmbed + - SpotterEmbed + - SpotterAgentEmbed + - ConversationEmbed + - PreRenderedLiveboardEmbed + + # Product feature nouns + - Liveboard + - Liveboards + - Worksheet + - Worksheets + - TML + - GUID + + # Auth and security terms + - TrustedAuthToken + - TrustedAuthTokenCookieless + - AuthType + - SAML + - SSO + - CORS + - RBAC + - ABAC + - RLS + - CRUD + + # Languages and frameworks + - JavaScript + - TypeScript + - React + - Antora + + # Additional acronyms + - CSV + - PDF + - JWT + + # Cloud and integration partners + - Salesforce + - Snowflake + - Databricks + - Google + - Microsoft + - Slack + - Vercel + - Pendo + + # ------------------------------------------------------- + # ADD YOUR OWN PROPER NOUNS BELOW + # Format: - TermToKeepCapitalised + # ------------------------------------------------------- diff --git a/.vale/styles/ts-docs/LinkText.yml b/.vale/styles/ts-docs/LinkText.yml new file mode 100644 index 000000000..bccbb8329 --- /dev/null +++ b/.vale/styles/ts-docs/LinkText.yml @@ -0,0 +1,17 @@ +# ts-docs/LinkText.yml +# Flags non-descriptive link text that violates accessibility +# and ThoughtSpot style guidelines. +# Rule: linked text must tell the reader what they are clicking on. +# Do not link more than three to four words. +extends: existence +message: "Avoid '%s' as link text. Use words that tell the reader what they are clicking on." +level: warning +ignorecase: true +tokens: + - 'click here' + - 'click this link' + - 'click here to' + - 'read more' + - 'learn more' + - 'here\.' + - 'this link' diff --git a/.vale/styles/ts-docs/PreCommitChecks.yml b/.vale/styles/ts-docs/PreCommitChecks.yml new file mode 100644 index 000000000..0a4800da1 --- /dev/null +++ b/.vale/styles/ts-docs/PreCommitChecks.yml @@ -0,0 +1,54 @@ +# ts-docs/PreCommitChecks.yml +# Flags content that must be removed or replaced before committing. +# Covers unfilled template tokens and Git merge conflict markers. +# Applied to raw source (raw:) so tokens in AsciiDoc attributes +# and headers are also caught. +extends: existence +message: "Pre-commit issue: '%s' — remove or replace before committing." +level: error +nonword: true +raw: + # ---- Standard template tokens --------------------------- + - '<version>' + - '<Title' + - '<slug>' + - 'DOC-XXXX' + - 'JIRA-REF' + - 'ENG-XXXX' + - 'your-style-guide-url' + + # ---- In-template TODO comments -------------------------- + - 'TODO: verify with engineering' + - 'TODO: verify scope with engineering' + - 'TODO: add screenshot' + - 'TODO: confirm with' + + # ---- ThoughtSpot template tokens ------------------------ + # Tokens used in modules/_templates/*.adoc that must be + # replaced before a page is published. + - '<Title: ' + - '<Title —' + - '<One sentence:' + - '<Add a unique ID' + - '<comma-separated terms' + - '<version>' + - '<DOC-XXXX>' + - '<role or permission' + - '<system or resource' + - '<file-name>' + - 'your-instance' + - 'liveboard-GUID' + - '<your-instance>' + - '<liveboard-GUID>' + - '<username>' + - '<token>' + - '<endpoint>' + + # ---- Add your own template placeholder patterns --------- + # - '<YOUR-TOKEN>' + + # ---- Git merge conflict markers ------------------------- + # These must never appear in committed or published content. + - '^<{7}\s.*$' + - '^={7}$' + - '^>{7}\s.*$' diff --git a/.vale/styles/ts-docs/RepeatedWords.yml b/.vale/styles/ts-docs/RepeatedWords.yml new file mode 100644 index 000000000..1752ad930 --- /dev/null +++ b/.vale/styles/ts-docs/RepeatedWords.yml @@ -0,0 +1,17 @@ +# ts-docs/RepeatedWords.yml +# Flags consecutive repeated words, e.g. "the the" or "and and". +# Ported from RedHat.RepeatedWords. +extends: repetition +message: "'%s' is repeated. Remove the duplicate." +level: warning +ignorecase: false +alpha: true +action: + name: edit + params: + - regex + - '(\w+)(\s\w+)' + - "$1" +tokens: + - '[^\s\.]+' + - '[^\s]+' diff --git a/.vale/styles/ts-docs/SentenceLength.yml b/.vale/styles/ts-docs/SentenceLength.yml new file mode 100644 index 000000000..36a32392c --- /dev/null +++ b/.vale/styles/ts-docs/SentenceLength.yml @@ -0,0 +1,11 @@ +# ts-docs/SentenceLength.yml +# Flags sentences in paragraph prose that exceed 30 words. +# Code blocks, headings, lists, and other non-prose content +# are ignored automatically by Vale's AsciiDoc parser. +# Raise max if the rule is too noisy for your content. +extends: occurrence +message: "Long sentence (%d words). Aim for 30 or fewer." +level: suggestion +scope: sentence +max: 30 +token: '\b\w+' diff --git a/.vale/styles/ts-docs/SmartQuotes.yml b/.vale/styles/ts-docs/SmartQuotes.yml new file mode 100644 index 000000000..4ebbf970b --- /dev/null +++ b/.vale/styles/ts-docs/SmartQuotes.yml @@ -0,0 +1,16 @@ +# ts-docs/SmartQuotes.yml +# Flags curly/smart quotation marks in raw AsciiDoc source. +# AsciiDoc source should use straight ASCII quotes; the renderer +# applies typographic quotes as needed. Curly quotes in source +# can cause rendering issues and encoding problems. +# Ported from RedHat.SmartQuotes. +extends: substitution +message: "Do not use curly/smart quotation marks. Use straight ASCII quotes instead of '%s'." +level: warning +nonword: true +scope: raw +action: + name: replace +swap: + '\u2018|\u2019': "'" + '\u201C|\u201D|\u201F|\u2033|\u2036': '"' diff --git a/.vale/styles/ts-docs/WordList.yml b/.vale/styles/ts-docs/WordList.yml new file mode 100644 index 000000000..defae7967 --- /dev/null +++ b/.vale/styles/ts-docs/WordList.yml @@ -0,0 +1,212 @@ +# ts-docs/WordList.yml +# Adapted from github.com/splunk/vale-splunk-style-guide +# Flags variant or deprecated terms and suggests the preferred form. +extends: substitution +message: "Use '%s' instead of '%s'." +level: warning +ignorecase: false +action: + name: replace +swap: + # ------------------------------------------------------- + # UI INTERACTION TERMS + # ------------------------------------------------------- + 'click on': click + 'hit': press + 'depress': press + 'check out': see + + # ------------------------------------------------------- + # DIRECTIONAL REFERENCES + # Replace spatial directions with relative document refs + # ------------------------------------------------------- + 'above': the previous section + 'below': the following section + + # ------------------------------------------------------- + # WORDY PHRASES - replace with concise alternatives + # ------------------------------------------------------- + 'in order to': to + 'due to the fact that': because + 'at this point in time': now + 'at present': now + 'basic steps': steps + 'be sure to': make sure + 'in the event that': if + 'prior to': before + 'subsequent to': after + 'with regard to': about + 'with respect to': about + 'as per': per + 'a number of': several|many + + # ------------------------------------------------------- + # TECHNICAL TERM CONSISTENCY + # ------------------------------------------------------- + 'boolean': Boolean + 'can not': cannot + 'checkbox': check box + 'carriage return': line break + 'utilize': use + 'utilization': usage + 'leverage': use + 'functionality': features + 'performant': high-performance + + # ------------------------------------------------------- + # INCLUSIVE LANGUAGE + # ------------------------------------------------------- + 'whitelist': allowlist + 'blacklist': blocklist + 'master branch': main branch + 'dummy': placeholder|stub + 'sanity check': confidence check|smoke test + + # ------------------------------------------------------- + # THOUGHTSPOT PRODUCT-SPECIFIC TERMS + # Applies to prose text only - code blocks, URLs, and + # parameter/variable names are excluded by Vale's + # AsciiDoc parser before these rules run. + # ------------------------------------------------------- + + # Deprecated plain-English feature names (prose only) + 'pinboard': Liveboard + 'Pinboard': Liveboard + 'sage embed': Spotter embed + 'sage search': natural language search + 'Ask sage': Ask AI + + # Worksheet deprecated - replaced by Model. + # Word boundaries ensure worksheetId and other SDK parameter + # names in code are never matched - only bare prose words fire. + # Context guide: + # UI element reference -> Model (capitalized) + # Descriptive prose -> model or data model (lowercase) + '\bworksheet\b': model + '\bWorksheet\b': Model + '\bworksheets\b': models + '\bWorksheets\b': Models + + + # Deprecated SDK class names referenced in prose + # (e.g. "Use SageEmbed to..." in a migration guide) + 'SageEmbed': SpotterEmbed + 'SageEmbedQuery': SpotterEmbed + 'PinboardEmbed': LiveboardEmbed + 'PinboardEmbedViewConfig': LiveboardViewConfig + + # ------------------------------------------------------- + # THOUGHTSPOT WRITING CONVENTIONS + # Source: ThoughtSpot style guide + # ------------------------------------------------------- + + # Brand abbreviations - always write the full name in external content + '\bTS\b': ThoughtSpot + '\bTSE\b': ThoughtSpot Embedded + + # All-caps variant — incorrect casing, suggest correct brand name + '\bTHOUGHTSPOT\b': ThoughtSpot + + # Deprecated product name - replaced by ThoughtSpot Embedded + '\bThoughtSpot Everywhere\b': ThoughtSpot Embedded + + # Acronym style - no periods (use AI not A.I.) + 'A\.I\.': AI + 'B\.I\.': BI + + # Compound word and hyphenation conventions + 'dropdown': drop-down + 'drop down': drop-down + '[Ee]-mail': email + '[Ee]-book': ebook + 'front line': frontline + 'front-line': frontline + 'white paper': whitepaper + + # ThoughtSpot product and feature naming + 'liveboards': Liveboards + 'live analytics': Live Analytics + 'data lakehouse': lakehouse + '[Rr]eal-time insights': Instant insights + 'zero to search': zero-to-search + + # Use low-code, not no-code + 'no-code': low-code + + # ------------------------------------------------------- + # PLAIN ALTERNATIVES (from IBM/RedHat SimpleWords) + # Prefer plain alternatives in technical writing. + # ------------------------------------------------------- + 'commence': begin + 'initiate': start|begin + 'numerous': many + 'a lot of': many|much + + # ------------------------------------------------------- + # WORDY PHRASES (from Microsoft.Wordiness) + # ------------------------------------------------------- + 'has the ability to': can + 'has the capacity to': can + 'whether or not': whether + 'despite the fact that': although + 'because of the fact that': because + 'successfully complete': complete + 'take into account': consider + 'in lieu of': instead of + 'make reference to': refer to + 'made reference to': referred to + 'with the exception of': except for + 'except when': unless + 'not in a position to': unable + 'in many cases': often + 'in most cases': usually + 'a (?:large)? majority of': most + 'a myriad of': myriad + 'any and all': all + 'at all times': always + 'at a later date': later + 'continue on': continue + 'during the period of': during + 'during the time that': while + 'establish connectivity': connect + 'for the duration of': during + 'in an effort to': to + 'in between': between + 'in spite of the fact that': although + 'pertaining to': about + 'until such time as': until + + # ------------------------------------------------------- + # TERMS ADOPTED FROM GOOGLE DEVELOPER STYLE GUIDE + # Google.WordList is suppressed in .vale.ini; applicable + # entries are maintained here instead. + # Excluded: Google-specific product names (Cloud, Container + # Engine, Developers Console), Android/mobile-only terms, + # and entries already covered above. + # ------------------------------------------------------- + + # Auth and security + '(?:OAuth ?2|Oauth)': OAuth 2.0 + 'authN': authentication + 'authZ': authorization + 'SHA1': SHA-1 + 'sign into': sign in to + + # Capitalization and spelling + '(?:WiFi|wifi)': Wi-Fi + 'HTTPs': HTTPS + '\burl\b': URL + 'synch': sync + 'k8s': Kubernetes + + # Technical writing conventions + 'data are': data is + 'file name': filename + 'a\.k\.a|aka': or|also known as + 'vs\.': versus + 'approx\.': approximately + 'autoupdate': automatically update + + # UI actions + 'un(?:check|select)': clear + '(?:kill|terminate|abort)': stop|exit|cancel|end diff --git a/.valeignore b/.valeignore new file mode 100644 index 000000000..b92abd6c5 --- /dev/null +++ b/.valeignore @@ -0,0 +1,24 @@ +# Vale ignore patterns — syntax mirrors .gitignore +# Paths matched here are skipped entirely by `vale`. + +# Build output and dependencies +node_modules/ +public/ +.cache/ +dist/ +lib/ +coverage/ + +# Auto-generated TypeDoc pages — not authored prose +modules/ROOT/pages/generated/ + +# Legacy / deprecated embed pages (kept for reference, not linted) +# Uncomment if you want to suppress alerts on legacy pages: +# modules/ROOT/pages/embed-pinboard.adoc +# modules/ROOT/pages/pinboard-export-api.adoc + +# Vale style packages and config — not authored prose +.vale/styles/Google/ +.vale/styles/Microsoft/ +.vale/styles/ts-docs/ +.vale/styles/config/ diff --git a/modules/ROOT/pages/authentication.adoc b/modules/ROOT/pages/authentication.adoc index 4d0b69cf0..f84f56343 100644 --- a/modules/ROOT/pages/authentication.adoc +++ b/modules/ROOT/pages/authentication.adoc @@ -117,7 +117,7 @@ To get an access token that grants full access to ThoughtSpot, send a `POST` req |`org_id` + __Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). |`validity_time_in_sec` + -__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls. +__Optional__ |__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. You can set the token expiry duration to a higher value. API requests with an expired or invalid token result in an error. In such cases, REST clients must obtain a new token from ThoughtSpot and use it in their subsequent API calls. || |===== @@ -245,9 +245,9 @@ To get a token that grants read-only access to a ThoughtSpot metadata object, se |__String__. GUID of the ThoughtSpot object. The token obtained from this API request grants `read-only` access to the specified object. |`org_id` + -__Optional__|__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). +__Optional__ |__Integer__. If the Orgs feature is enabled on your instance, specify the ID of the Org for which you want to generate the authentication token. If no value is specified, the token is generated for the Primary Org (Org 0). |`validity_time_in_sec` + -__Optional__|__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. +__Optional__ |__Integer__. Token validity duration in seconds. By default, the token is valid for 5 minutes. |===== ===== Example request diff --git a/modules/ROOT/pages/variables.adoc b/modules/ROOT/pages/variables.adoc index a5d4ce38b..f58cb6dd6 100644 --- a/modules/ROOT/pages/variables.adoc +++ b/modules/ROOT/pages/variables.adoc @@ -8,6 +8,7 @@ Variables allow you to substitute values for specific properties of a metadata object and enable dynamic data propagation across Orgs in ThoughtSpot. Using variables, you can parameterize the properties of data connections, table references, and formulas per Org without changing the underlying data or creating duplicate objects. Variable values are assigned at runtime to ensure that customized configuration is available to users of different Orgs in ThoughtSpot. + == Overview ThoughtSpot provides predefined system variables such as `ts_username` and `ts_groups`, which can be used in formulas for data security. Additionally, you can configure variables programmatically via REST APIs, and later use these variables for the following purposes: diff --git a/modules/_templates/best-practices.adoc b/modules/_templates/best-practices.adoc new file mode 100644 index 000000000..ab2544792 --- /dev/null +++ b/modules/_templates/best-practices.adoc @@ -0,0 +1,79 @@ += <Title: "Best Practices for <noun phrase>"> +:toc: true +:toclevels: 1 + +:page-pageid: +:keywords: <comma-separated terms. For example, "configure auth", "SSO", "SAML"> +:page-type: best-practices +:page-role: +:product-version: <version> +:jira-ref: <DOC-XXXX> +// last-reviewed: <Optional> + +// 1-2 sentences: what this page covers, who it is for, and what +// following these practices helps them achieve. + +== Overview + +// Optional. Provide context for why these practices matter +// what problems they prevent or what outcomes they enable. +// Keep to 2-3 sentences. Link to concept pages for deeper background. + +== Recommended practices +// Include a list the best practices, dos and don'ts. + +// * <Do not set the token expiration key to ...> +// * <Ensure the API token is saved in a secure place.> + +// If a best practice or recommendation requires its own section, use the format in the following sections.> + +=== <Practice title: short imperative phrase, "Refresh API keys regularly"> + +// Lead with the recommendation as a direct statement: +// "Refresh your API keys every 90 days." +// +// Then explain: +// - Why: the risk or benefit this practice addresses +// - How: the steps or configuration required +// - When: any conditions or exceptions that apply + +// TODO: verify recommendation with engineering + +[source,bash] +---- +# Example command or configuration snippet if applicable +---- + +// NOTE: <Optional note that helps the reader apply this practice more effectively.> + +=== <Practice title> + +// Lead with the recommendation. +// Explain why, how, and when. + +== What to avoid + +// Optional but high value. Describe common mistakes or patterns. +// Use WARNING admonitions for practices that risk data loss or security issues. + +//WARNING: <Describe a practice that risks data loss, security exposure,or system instability. State the consequence clearly.> + +// Alternative: use a simple list for lower-severity anti-patterns. + +// Optional but high value. Describe common mistakes, patterns, dos and don'ts. + +// * <Do not set the token expiration key to less than 10 minutes>, <state the reason/impact and preferred alternative>. +// * <Do not ....> <state the reason/impact and preferred alternative>. + +// Use admonitions to highlight important information. + +//// +[WARNING] +=== +<Describe a practice that risks data loss, security exposure,or system instability. State the consequence clearly.> +==== +//// + +== Related information + +// * xref:<file-name>.adoc[Link text] <Add additional info or subtext if required. diff --git a/modules/_templates/concept.adoc b/modules/_templates/concept.adoc index d21cac891..9b143ec75 100644 --- a/modules/_templates/concept.adoc +++ b/modules/_templates/concept.adoc @@ -4,8 +4,8 @@ :page-title: <Title — must match the = Title above> :page-description: <One sentence: what this page covers and why it matters to the reader.> -:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.> -:keywords: <comma-separated terms for search indexing, e.g. "authentication, SSO, SAML, login"> +:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.> +:keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login"> :page-type: concept :page-role: :product-version: <version> @@ -21,7 +21,7 @@ TEMPLATE GUIDE ============== How to use this template: 1. Copy this file from modules/_templates/concept.adoc. - 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "embed-sso-overview.adoc"). + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "embed-sso-overview.adoc"). 3. Place the file in modules/ROOT/pages/. 4. If this page will be included as a partial inside another page (via include::), remove all front-matter attributes — partials do not need them. @@ -92,7 +92,7 @@ Description of what it does. == Limitations and constraints // RECOMMENDED. -// List known limitations, version-specific behaviour, or edge cases the reader should know. +// List known limitations, version-specific behavior, or edge cases the reader should know. // Use admonitions for critical constraints: // // [IMPORTANT] @@ -102,7 +102,7 @@ Description of what it does. // // [NOTE] // ==== -// Behaviour changed in <version>. If you are on an earlier version, see xref:...[] +// Behavior changed in <version>. If you are on an earlier version, see xref:...[] // ==== // // [WARNING] @@ -110,7 +110,7 @@ Description of what it does. // Enabling this setting affects all users in the org. Confirm with your administrator before proceeding. // ==== -* +* <Known limitation or constraint.> == Related information diff --git a/modules/_templates/faqs.adoc b/modules/_templates/faqs.adoc new file mode 100644 index 000000000..a22c03184 --- /dev/null +++ b/modules/_templates/faqs.adoc @@ -0,0 +1,64 @@ += <Title: Noun phrase, for example, "Frequently Asked Questions: Authentication"> +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: faq +:page-role: +:product-version: <version> +:jira-ref: <DOC-XXXX> +// author: +// last-reviewed: + +// 1-2 sentences: what topic area these FAQs cover and who they are for. +// Note: write each question as users would ask it — this improves +// both findability and GEO citation rates. + +== General + +=== <Question written as a user would ask it, for example, "What authentication methods are supported?"> + +// Answer directly in the first sentence. Provide detail after. +// If the answer requires steps, use a numbered list. +// If the answer links to a full page, link to it and summarize here. + +// TODO: verify answer with engineering + +--- + +=== <Question> + +// Answer. + +== <Topic group, for example, "Installation"> + +=== <Question> + +// Answer. + +--- + +=== <Question> + +// Answer. + +== <Topic group, for example, "Configuration"> + +=== <Question> + +// Answer. + +--- + +=== <Question> + +// Answer. + +== <Topic group, for example, "Billing and licensing"> + +=== <Question> + +// Answer. + +== Related information + +* xref:<component>:<module>/page.adoc[Link text] diff --git a/modules/_templates/procedure.adoc b/modules/_templates/procedure.adoc index 597a571b2..bdda044df 100644 --- a/modules/_templates/procedure.adoc +++ b/modules/_templates/procedure.adoc @@ -1,12 +1,12 @@ -= <Title: Verb + Object, e.g. "Configure Single Sign-On"> += <Title: Verb + Object, for example, "Configure Single Sign-On"> :toc: true :toclevels: 1 :page-title: <Title — must match the = Title above> :page-description: <One sentence: what this procedure does and who it is for.> -:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.> +:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.> :page-type: procedure -:keywords: <comma-separated terms for search indexing, e.g. "configure, SSO, SAML, setup"> +:keywords: <comma-separated terms for search indexing, for example, "configure, SSO, SAML, setup"> :page-role: :product-version: <version> :jira-ref: <DOC-XXXX> @@ -18,7 +18,7 @@ TEMPLATE GUIDE ============== How to use this template: 1. Copy this file from modules/_templates/procedure.adoc. - 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "configure-saml-sso.adoc"). + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "configure-saml-sso.adoc"). 3. Place the file in modules/ROOT/pages/. 4. If this page will be included as a partial inside another page (via include::), remove all front-matter attributes — partials do not need them. @@ -61,8 +61,8 @@ Style elements you can use: // REQUIRED if there are prerequisites. Use "You must" or "You need" for each item. // Remove this section only if there are genuinely no prerequisites. -* You must have <role or permission, e.g. "Developer or Administrator privilege">. -* You need access to <system or resource, e.g. "a ThoughtSpot Cloud instance with the Embed feature enabled">. +* You must have <role or permission, for example, "Developer or Administrator privilege">. +* You need access to <system or resource, for example, "a ThoughtSpot Cloud instance with the Embed feature enabled">. * <Any additional prerequisite.> == Procedure @@ -130,7 +130,7 @@ curl -X POST \ == Result // REQUIRED. Describe what the user should see or be able to do after completing the procedure. -// Be specific — name the UI element, API response, or behaviour that confirms success. +// Be specific — name the UI element, API response, or behavior that confirms success. // // OPTIONAL: Screenshot of the expected result: // image::./images/<result-screenshot>.png[Expected result after completing the procedure] diff --git a/modules/_templates/quickstart.adoc b/modules/_templates/quickstart.adoc new file mode 100644 index 000000000..44de8de34 --- /dev/null +++ b/modules/_templates/quickstart.adoc @@ -0,0 +1,113 @@ += Get Started with <Product or Feature Name> +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: quickstart +:page-role: +:product-version: <version> +:jira-ref: <DOC-XXXX> +// author: +// last-reviewed: + +// 1-2 sentences: what the user will have running or achieved by the +// end of this page, and roughly how long it takes. +// Example: "This guide walks you through installing and configuring +// <Product> for the first time. Estimated time: 15 minutes." + +== Before you begin + +// List everything the user must have in place before starting. +// Be specific — vague prerequisites are the most common cause of +// support requests on getting-started content. + +Ensure you have the following before proceeding: + +* *Operating system*: <supported OS and minimum version> +* *<Dependency>*: version <X.X> or later. See xref:<component>:<module>/page.adoc[Install <Dependency>]. +* *Permissions*: <describe required access level or role> +* *Network access*: <describe any firewall, port, or connectivity requirements> +// TODO: verify prerequisites with engineering + +== Step 1: <First milestone, for example, "Install <Product>"> + +// Keep each step focused on a single milestone the user can verify. +// Use a numbered list for the actions within each step. + +. Action one. ++ +[source,bash] +---- +# example command +---- + +. Action two. + +. Verify the installation was successful: ++ +[source,bash] +---- +# verification command +---- ++ +Expected output: ++ +---- +<expected output here> +---- + +== Step 2: <Second milestone, for example, "Configure your environment"> + +. Action one. ++ +[source,bash] +---- +# example command or configuration snippet +---- + +. Action two. + +// TODO: verify configuration steps with engineering + +== Step 3: <Third milestone, for example, "Run your first <action>"> + +. Action one. +. Action two. ++ +[source,bash] +---- +# example command +---- + +. Verify the result: ++ +---- +<expected output here> +---- + +== Next steps + +// Tell the user what to do now that they have a working setup. +// Link to tutorials, deeper configuration guides, or key concepts. + +Now that you have <Product> running, you can: + +* xref:<component>:<module>/page.adoc[<Next logical task>] +* xref:<component>:<module>/page.adoc[<Explore a key feature>] +* xref:<component>:<module>/page.adoc[<Understand a core concept>] + +== Troubleshooting + +// Optional. Cover the 2-3 most common issues users hit during setup. +// Link to the full troubleshooting page if one exists. + +If you encounter issues during setup, see +xref:<component>:<module>/troubleshooting.adoc[Troubleshoot <Product> installation]. + +Common issues: + +* *<Symptom>*: <one-line cause and fix>. +* *<Symptom>*: <one-line cause and fix>. + +== Related information + +* xref:<component>:<module>/page.adoc[Link text] diff --git a/modules/_templates/reference.adoc b/modules/_templates/reference.adoc index 8dfdec29c..a1b1ab16c 100644 --- a/modules/_templates/reference.adoc +++ b/modules/_templates/reference.adoc @@ -1,10 +1,11 @@ -= <Title: Noun phrase, e.g. "Liveboard report API reference"> += <Title: Noun phrase, for example, "Liveboard report API reference"> :toc: true -:toclevels: 1 <-- adjust if you have many sections, but 1-2 levels is usually sufficient for reference pages> +:toclevels: 1 +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. :page-title: <Title — must match the = Title above> :page-description: <One sentence: what this reference documents and who uses it.> -:keywords: <comma-separated terms for search indexing, e.g. "REST API, parameters, endpoints, reference"> +:keywords: <comma-separated terms for search indexing, for example, "REST API, parameters, endpoints, reference"> :page-pageid: :page-type: reference :page-role: @@ -18,12 +19,12 @@ TEMPLATE GUIDE ============== How to use this template: 1. Copy this file from modules/_templates/reference.adoc. - 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "rest-api-auth-reference.adoc"). + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "rest-api-auth-reference.adoc"). 3. Place the file in modules/ROOT/pages/. 4. If this page will be included as a partial inside another page (via include::), remove all front-matter attributes — partials do not need them. -Use this template for pages that document parameters, properties, endpoints, request /response worklows, classes, enumerations, or configuration options — reference material a reader looks up, not reads start-to-finish. +Use this template for pages that document parameters, properties, endpoints, request/response workflows, classes, enumerations, or configuration options — reference material a reader looks up, not reads start-to-finish. Section labels: REQUIRED — must be present on every page of this type @@ -111,7 +112,7 @@ POST /api/rest/2.0/<endpoint-path> // OPTIONAL: Version-specific notes — use inline badges to flag changes per parameter: // [.version-badge.new]#New in vX.X# `new_param` — added in this version; description. // [.version-badge.deprecated]#Deprecated# `old_param` — deprecated in vX.X; use `new_param` instead. -// [.version-badge.breaking]#Breaking# `changed_param` — behaviour changed in vX.X. +// [.version-badge.breaking]#Breaking# `changed_param` — behavior changed in vX.X. === Example request diff --git a/modules/_templates/release-notes.adoc b/modules/_templates/release-notes.adoc index a9379d3e0..80a092a0d 100644 --- a/modules/_templates/release-notes.adoc +++ b/modules/_templates/release-notes.adoc @@ -3,7 +3,7 @@ :toclevels: 1 :page-title: <Title — must match the = Title above> :page-description: <One sentence: summary of what is new or changed in this release.> -:keywords: <comma-separated terms for search indexing, e.g. "release notes, changelog, new features, ThoughtSpot Cloud"> +:keywords: <comma-separated terms for search indexing, for example, "release notes, changelog, new features"> :page-type: release-note :page-role: :product-version: <version> @@ -14,7 +14,7 @@ TEMPLATE GUIDE ============== How to use this template: 1. Copy this file from modules/_templates/release-notes.adoc. - 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "release-notes-26-5.adoc"). + 2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, for example, "release-notes-26-5.adoc"). 3. Place the file in modules/ROOT/pages/. 4. If this page will be included as a partial inside another page (via include::), remove all front-matter attributes — partials do not need them. @@ -49,10 +49,10 @@ Format notes: //// // REQUIRED: One sentence stating the release scope and any critical headline. -This release includes updates to <product area, e.g. "the Visual Embed SDK and REST API v2.0">. +This release includes updates to <product area, for example, "the Visual Embed SDK and embed APIs">. // REQUIRED: Release metadata block. -**Release version**: ThoughtSpot Cloud <X.X.X.cl> + +*Release version*: ThoughtSpot Cloud <version> + *Upgrade notes*: <None. / ⚠️ Describe any breaking changes; link to Upgrade notes section.> + *Recommended SDK versions*: Visual Embed SDK v<X.XX.X> and later diff --git a/modules/_templates/troubleshooting.adoc b/modules/_templates/troubleshooting.adoc new file mode 100644 index 000000000..6ec2b685b --- /dev/null +++ b/modules/_templates/troubleshooting.adoc @@ -0,0 +1,90 @@ += <Title: Noun phrase describing the problem area, for example, "Troubleshoot Authentication Errors"> +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: troubleshooting +:page-role: +:product-version: <version> +:jira-ref: <DOC-XXXX> +// author: +// last-reviewed: + +// 1-2 sentences: what issues this page helps resolve and who it is for. + +== General troubleshooting steps + +// Optional. Steps to try before attempting issue-specific fixes. +// Remove this section if all issues have distinct, unrelated causes. + +. Check that you are running the correct version. See xref:<component>:<module>/page.adoc[Supported versions]. +. Review the logs for error messages. Log files are located at `<log-path>`. +. // TODO: verify general steps with engineering + +== Issues + +=== <Issue title: brief description of the symptom, for example, "Connection times out after login"> + +==== Symptom + +// Describe exactly what the user sees: error message text, UI behavior, +// or unexpected output. Use a literal block for exact error messages. + +---- +<exact error message or log output here> +---- + +==== Cause + +// Explain why this happens. If the cause is unknown, write: +// "The cause of this issue has not been determined." +// TODO: verify cause with engineering + +==== Solution + +. Step one. +. Step two. +. Step three. + +// If there are multiple solutions, use separate numbered lists with +// a lead-in sentence for each: "If <condition>, try the following:" + +==== Verification + +// Optional. Describe what the user should see to confirm the issue is resolved. + +--- + +=== <Issue title> + +==== Symptom + +---- +<exact error message or log output here> +---- + +==== Cause + +// TODO: verify cause with engineering + +==== Solution + +. Step one. +. Step two. + +==== Verification + +// Optional. + +== Collect diagnostic information + +// Optional but recommended. Describe how to gather logs, traces, +// or system information to share with support. + +[source,bash] +---- +# Example command to collect diagnostic output +---- + +== Related information + +* xref:<component>:<module>/page.adoc[Link text] diff --git a/modules/_templates/tutorial.adoc b/modules/_templates/tutorial.adoc new file mode 100644 index 000000000..a1d011266 --- /dev/null +++ b/modules/_templates/tutorial.adoc @@ -0,0 +1,229 @@ += <Title: Action-oriented phrase describing what the user builds, +for example, "Build a Real-Time Dashboard Using the <Product> API"> +:toc: true +:toclevels: 1 +:page-pageid: +:page-type: tutorial +:page-role: +:product-version: <version> +:jira-ref: <DOC-XXXX> +// author: +// last-reviewed: + +// 2-3 sentences covering: +// - What the user will build or accomplish +// - What they will learn along the way +// - Estimated time to complete +// Example: "In this tutorial, you build a <thing> using <Product>. +// You learn how to <skill 1>, <skill 2>, and <skill 3>. +// Estimated time: 30 minutes." + +== Learning objectives + +// List what the user will be able to do after completing this tutorial. +// Use "After completing this tutorial, you will be able to:" as the lead. +// Write each objective as a verb phrase. + +After completing this tutorial, you will be able to: + +* <Verb phrase, for example, "Configure a <Product> connection using OAuth 2.0"> +* <Verb phrase> +* <Verb phrase> + +== Before you begin + +// List prerequisites with enough specificity that the user can +// self-qualify before investing time in the tutorial. + +* *Experience level*: <for example, "Familiarity with REST APIs and JSON"> +* *<Tool or dependency>*: version <X.X> or later installed and configured. + See xref:<component>:<module>/page.adoc[Install <Tool>]. +* *<Account or access>*: <describe what is needed and how to obtain it> +* *Completed*: xref:<component>:<module>/quickstart.adoc[Get Started with <Product>] +// TODO: verify prerequisites with engineering + +== Overview + +// Optional but recommended for tutorials over 20 minutes. +// Briefly describe the architecture, workflow, or scenario the +// user is working through, so they understand the big picture +// before diving into steps. A diagram (image::) works well here. + +In this tutorial, you: + +. <High-level phase 1, for example, "Set up the project structure"> +. <High-level phase 2, for example, "Configure authentication"> +. <High-level phase 3, for example, "Implement the core logic"> +. <High-level phase 4, for example, "Test and verify the result"> + +== Part 1: <Phase title, for example, "Set up the project"> + +// Tutorials are longer than procedures. Use H2 parts to divide +// the work into phases the user can pause and resume between. +// Each part should produce a verifiable intermediate result. + +<Context sentence: explain what this part accomplishes and why +it comes first.> + +. Action one. ++ +[source,bash] +---- +# example command +---- + +. Action two. ++ +[source,<language>] +---- +// example code +---- + +. Action three. + +=== Checkpoint + +// End each part with a checkpoint so the user can verify their +// work before continuing. A failed checkpoint at part 2 is much +// easier to recover from than discovering an error at part 5. + +Verify that <expected state>: + +[source,bash] +---- +# verification command +---- + +Expected output: + +---- +<expected output> +---- + +If you see <unexpected output>, see <<troubleshooting>> at the end +of this tutorial. + +== Part 2: <Phase title> + +<Context sentence.> + +. Action one. ++ +[source,<language>] +---- +// example code +---- + +. Action two. + +. Action three. ++ +[source,<language>] +---- +// example code +---- + +=== Checkpoint + +Verify that <expected state>: + +[source,bash] +---- +# verification command +---- + +// TODO: verify steps and expected output with engineering + +== Part 3: <Phase title> + +<Context sentence.> + +. Action one. +. Action two. +. Action three. + +=== Checkpoint + +Verify that <expected state>: + +[source,bash] +---- +# verification command +---- + +== Part 4: <Phase title> + +<Context sentence.> + +. Action one. +. Action two. +. Action three. + +=== Checkpoint + +Verify that <expected state>: + +[source,bash] +---- +# verification command +---- + +== Summary + +// Briefly recap what the user built and what they learned. +// Reinforce the learning objectives from the top of the page. + +In this tutorial, you: + +* <Past-tense summary of what was built or configured> +* <Past-tense summary of a key skill practiced> +* <Past-tense summary of a key concept applied> + +== Clean up + +// Optional but important for tutorials involving cloud resources, +// paid services, or system changes the user may want to reverse. + +To remove the resources created in this tutorial: + +. Step one. +. Step two. ++ +[source,bash] +---- +# cleanup command +---- + +== Next steps + +// Point the user toward the logical next tutorial, a deeper +// feature guide, or the full reference documentation. + +* xref:<component>:<module>/page.adoc[<Next tutorial in the series>] +* xref:<component>:<module>/page.adoc[<Deeper feature guide>] +* xref:<component>:<module>/page.adoc[<Related best practices>] + +[#troubleshooting] +== Troubleshooting + +// Cover issues specific to this tutorial — configuration mistakes, +// environment differences, and common errors at checkpoint steps. + +[cols="1,2", options="header"] +|=== +|Symptom |Solution + +|<Error message or unexpected behavior> +|<Cause and fix> + +|<Error message or unexpected behavior> +|<Cause and fix> + +|=== + +For general troubleshooting, see +xref:<component>:<module>/troubleshooting.adoc[Troubleshoot <Product>]. + +== Related information + +* xref:<component>:<module>/page.adoc[Link text] From c98756f6c9cbaee8d59b4bd2bc37584bf71402fb Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <shashikala.subramanya@thoughtspot.com> Date: Wed, 27 May 2026 00:25:20 +0530 Subject: [PATCH 4/5] templates --- modules/_templates/best-practices.adoc | 10 +- modules/_templates/concept.adoc | 47 ++--- modules/_templates/faqs.adoc | 29 ++- modules/_templates/procedure.adoc | 70 +++----- modules/_templates/quickstart.adoc | 51 +++--- modules/_templates/reference.adoc | 59 ++---- modules/_templates/release-notes.adoc | 22 +-- modules/_templates/troubleshooting.adoc | 9 +- modules/_templates/tutorial.adoc | 229 ------------------------ 9 files changed, 121 insertions(+), 405 deletions(-) delete mode 100644 modules/_templates/tutorial.adoc diff --git a/modules/_templates/best-practices.adoc b/modules/_templates/best-practices.adoc index ab2544792..7229db838 100644 --- a/modules/_templates/best-practices.adoc +++ b/modules/_templates/best-practices.adoc @@ -1,13 +1,15 @@ = <Title: "Best Practices for <noun phrase>"> :toc: true :toclevels: 1 +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. -:page-pageid: +:page-title: <Title text for the page> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-best-practices"> :keywords: <comma-separated terms. For example, "configure auth", "SSO", "SAML"> :page-type: best-practices -:page-role: +:page-role: <Optional> :product-version: <version> -:jira-ref: <DOC-XXXX> +:jira-ref: <SCAL-XXXXXX> // last-reviewed: <Optional> // 1-2 sentences: what this page covers, who it is for, and what @@ -53,7 +55,7 @@ == What to avoid -// Optional but high value. Describe common mistakes or patterns. +// Optional but adds value. Describe common mistakes or patterns. // Use WARNING admonitions for practices that risk data loss or security issues. //WARNING: <Describe a practice that risks data loss, security exposure,or system instability. State the consequence clearly.> diff --git a/modules/_templates/concept.adoc b/modules/_templates/concept.adoc index 9b143ec75..6995cea60 100644 --- a/modules/_templates/concept.adoc +++ b/modules/_templates/concept.adoc @@ -1,20 +1,16 @@ = <Title: Noun phrase describing the concept> :toc: true :toclevels: 1 +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. -:page-title: <Title — must match the = Title above> +:page-title: <Title text for the page> :page-description: <One sentence: what this page covers and why it matters to the reader.> -:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "spotter-embed-overview"> :keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login"> -:page-type: concept -:page-role: +:page-role: <Optional> :product-version: <version> -:jira-ref: <DOC-XXXX> - -// author: -// last-reviewed: - -// REQUIRED: 1-2 sentence lead — what this concept is and why it matters to developers or administrators. +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> //// TEMPLATE GUIDE @@ -42,21 +38,29 @@ Style elements you can use: Inline badge : [beta betaBackground]^Beta^ Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# [.version-badge.breaking]#Breaking# [.version-badge.fixed]#Fixed# +============== //// + +// REQUIRED: a lead sentence for the article with 1-2 sentences. For example, explain what the feature is and why it matters to users. + +== Overview + +<Intro text> + == How <concept> works // REQUIRED. -// Explain the concept clearly. Avoid procedure steps — link to procedure pages instead. +// Explain the concept clearly. Avoid procedure steps. Link to procedure pages instead. // Use plain language; define acronyms on first use. // // Add a diagram or screenshot if spatial relationships or architecture matter: -// image::./images/<diagram-filename>.png[Alt text describing the diagram] -// -// Example: -// image::./images/embed-architecture.png[ThoughtSpot embedded architecture overview showing the SDK, REST API, and host application layers] +// Use the following format for images: +// image::./images/<diagram-filename>.png[Alt text describing the diagram] +// For example, image::./images/mcp-architecture.png[ThoughtSpot MCP Server architecture] // // Use admonitions to highlight key information: + // [NOTE] // ==== // Text for a general note or clarification. @@ -93,6 +97,8 @@ Description of what it does. // RECOMMENDED. // List known limitations, version-specific behavior, or edge cases the reader should know. +* <Known limitation or constraint.> + // Use admonitions for critical constraints: // // [IMPORTANT] @@ -110,12 +116,9 @@ Description of what it does. // Enabling this setting affects all users in the org. Confirm with your administrator before proceeding. // ==== -* <Known limitation or constraint.> - -== Related information +== Additional resources -// REQUIRED. -// Link to related concept, procedure, and reference pages. -// "Related information" is the standard heading — do not use "Additional resources" or "See also". +// REQUIRED. Include links to related concepts, procedures, and reference pages. -* xref:<module>/page.adoc[Link text] +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_blank] diff --git a/modules/_templates/faqs.adoc b/modules/_templates/faqs.adoc index a22c03184..c5a1803f7 100644 --- a/modules/_templates/faqs.adoc +++ b/modules/_templates/faqs.adoc @@ -1,19 +1,23 @@ = <Title: Noun phrase, for example, "Frequently Asked Questions: Authentication"> :toc: true :toclevels: 1 -:page-pageid: + + +:page-title: <Title text for the page> +:page-description: <One sentence: what this page covers and why it matters to the reader.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. The page ID must be unique. For example, "embed-faqs"> +:keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login"> :page-type: faq -:page-role: +:page-role: <Optional> :product-version: <version> -:jira-ref: <DOC-XXXX> -// author: -// last-reviewed: +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> // 1-2 sentences: what topic area these FAQs cover and who they are for. // Note: write each question as users would ask it — this improves // both findability and GEO citation rates. -== General +== <Information category. For example, Embed authentication> === <Question written as a user would ask it, for example, "What authentication methods are supported?"> @@ -21,10 +25,6 @@ // If the answer requires steps, use a numbered list. // If the answer links to a full page, link to it and summarize here. -// TODO: verify answer with engineering - ---- - === <Question> // Answer. @@ -35,8 +35,6 @@ // Answer. ---- - === <Question> // Answer. @@ -47,8 +45,6 @@ // Answer. ---- - === <Question> // Answer. @@ -61,4 +57,7 @@ == Related information -* xref:<component>:<module>/page.adoc[Link text] +// Optional. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_blank] diff --git a/modules/_templates/procedure.adoc b/modules/_templates/procedure.adoc index bdda044df..f75e0f255 100644 --- a/modules/_templates/procedure.adoc +++ b/modules/_templates/procedure.adoc @@ -1,16 +1,16 @@ = <Title: Verb + Object, for example, "Configure Single Sign-On"> :toc: true :toclevels: 1 +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. -:page-title: <Title — must match the = Title above> +:page-title: <Title text for the page> :page-description: <One sentence: what this procedure does and who it is for.> -:page-pageid: <Add a unique ID for this page, for example, "embed-sdk-concepts". Required for developer documentation.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page, for example, "embed-sdk-concepts".> :page-type: procedure :keywords: <comma-separated terms for search indexing, for example, "configure, SSO, SAML, setup"> :page-role: :product-version: <version> -:jira-ref: <DOC-XXXX> -// author: +:jira-ref: <SCAL-XXXXXX> // last-reviewed: //// @@ -44,28 +44,28 @@ Style elements you can use: Inline badge : [beta betaBackground]^Beta^ Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated# [.version-badge.breaking]#Breaking# + +============== //// == Overview // REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for. -// Mention the product area and the role of the reader (developer, administrator, etc.). -// TODO: verify scope with engineering -// -// OPTIONAL: Add a workflow diagram or screenshot of the starting UI state if it helps -// the reader orient themselves before starting: -// image::./images/<workflow-diagram>.png[Workflow overview diagram] +// Mention the product area and the intended audience (developer, administrator, etc.). + +// OPTIONAL: Add a workflow diagram or screenshot of the starting state if required. + == Before you begin // REQUIRED if there are prerequisites. Use "You must" or "You need" for each item. // Remove this section only if there are genuinely no prerequisites. -* You must have <role or permission, for example, "Developer or Administrator privilege">. +* You must have <role or group privilege> to <perform the intended action>. * You need access to <system or resource, for example, "a ThoughtSpot Cloud instance with the Embed feature enabled">. -* <Any additional prerequisite.> +* <Any additional prerequisite>. -== Procedure +== <Procedure. Use gerund or action verbs. For example, Configuring variables> // REQUIRED. Use numbered steps. Each step must describe exactly one action. // Include the exact command, UI label, menu path, or code for each step. @@ -75,33 +75,15 @@ Style elements you can use: + // OPTIONAL: Screenshot showing the UI state after this step: // image::./images/<step1-screenshot>.png[Description of what to see after step 1] +// For SDK procedures, a code sample is REQUIRED. Use the following format for code samples: -. Step two. For SDK procedures, provide a complete, runnable code sample — REQUIRED. -+ [source,JavaScript] ---- -import { LiveboardEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk'; - -init({ - thoughtSpotHost: 'https://<your-instance>.thoughtspot.cloud', - authType: AuthType.TrustedAuthToken, - username: '<username>', - getAuthToken: () => getTokenFromYourServer(), -}); - -const embed = new LiveboardEmbed('#embed-container', { - liveboardId: '<liveboard-GUID>', -}); -embed.render(); +<code sample> ---- -+ -[NOTE] -==== -Replace `<your-instance>` with your ThoughtSpot Cloud hostname and `<liveboard-GUID>` with the ID of the Liveboard you want to embed. -==== -. Step three. For REST API procedures, provide a cURL request — REQUIRED. -+ +// For REST API procedures, document the required parameters and provide request and response example. + [source,cURL] ---- curl -X POST \ @@ -112,7 +94,7 @@ curl -X POST \ "param": "value" }' ---- -+ + // OPTIONAL: Show the expected JSON response inline: // [source,JSON] // ---- @@ -130,22 +112,18 @@ curl -X POST \ == Result // REQUIRED. Describe what the user should see or be able to do after completing the procedure. -// Be specific — name the UI element, API response, or behavior that confirms success. -// +// Be specific. Specify the name the UI element, API response, or behavior that confirms success. // OPTIONAL: Screenshot of the expected result: -// image::./images/<result-screenshot>.png[Expected result after completing the procedure] == Next steps // OPTIONAL. Link to the next logical task or a related procedure. +// * xref:next-procedure.adoc[Next task name] -* xref:<module>/next-procedure.adoc[Next task name] -== Related information +== Additional resources -// REQUIRED. -// Link to related concept and reference pages. -// "Related information" is the standard heading — do not use "Additional resources" or "See also". +// REQUIRED. Include links to related concepts, procedures, and reference pages. -* xref:<module>/concept-page.adoc[Related concept] -* xref:<module>/reference-page.adoc[API reference] +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_blank] diff --git a/modules/_templates/quickstart.adoc b/modules/_templates/quickstart.adoc index 44de8de34..a9cc206f9 100644 --- a/modules/_templates/quickstart.adoc +++ b/modules/_templates/quickstart.adoc @@ -1,34 +1,27 @@ = Get Started with <Product or Feature Name> :toc: true :toclevels: 1 -:page-pageid: +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. + +:page-title: <Title text for the page> +:page-description: <One sentence: the purpose of quickstart guide does and who it is for.> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page. For example, "embedding-quickstart".> :page-type: quickstart :page-role: :product-version: <version> -:jira-ref: <DOC-XXXX> -// author: +:jira-ref: <SCAL-XXXXXX> // last-reviewed: -// 1-2 sentences: what the user will have running or achieved by the -// end of this page, and roughly how long it takes. -// Example: "This guide walks you through installing and configuring -// <Product> for the first time. Estimated time: 15 minutes." +// Intro text with 1-2 sentences: what the user will have running or achieved by the +// end of this page. +// Example: "This guide walks you through configuring MCP Server in a chatbot" == Before you begin // List everything the user must have in place before starting. -// Be specific — vague prerequisites are the most common cause of -// support requests on getting-started content. - -Ensure you have the following before proceeding: -* *Operating system*: <supported OS and minimum version> -* *<Dependency>*: version <X.X> or later. See xref:<component>:<module>/page.adoc[Install <Dependency>]. -* *Permissions*: <describe required access level or role> -* *Network access*: <describe any firewall, port, or connectivity requirements> -// TODO: verify prerequisites with engineering -== Step 1: <First milestone, for example, "Install <Product>"> +== Step 1: <First milestone, for example, "Add MCP Server"> // Keep each step focused on a single milestone the user can verify. // Use a numbered list for the actions within each step. @@ -66,7 +59,6 @@ Expected output: . Action two. -// TODO: verify configuration steps with engineering == Step 3: <Third milestone, for example, "Run your first <action>"> @@ -89,25 +81,24 @@ Expected output: // Tell the user what to do now that they have a working setup. // Link to tutorials, deeper configuration guides, or key concepts. -Now that you have <Product> running, you can: +Now that you have <feature> running, you can: -* xref:<component>:<module>/page.adoc[<Next logical task>] -* xref:<component>:<module>/page.adoc[<Explore a key feature>] -* xref:<component>:<module>/page.adoc[<Understand a core concept>] +* xref:page.adoc[<Next logical task>] +* xref:page1.adoc[<Explore a key feature>] +* xref:page2.adoc[<Understand a core concept>] == Troubleshooting // Optional. Cover the 2-3 most common issues users hit during setup. -// Link to the full troubleshooting page if one exists. -If you encounter issues during setup, see -xref:<component>:<module>/troubleshooting.adoc[Troubleshoot <Product> installation]. +* *<Issue*: <state the issue, cause, and fix/workaround>. +* *<Issue*: <state the issue, cause, and fix/workaround>. -Common issues: +// Link to the full troubleshooting page if one exists. -* *<Symptom>*: <one-line cause and fix>. -* *<Symptom>*: <one-line cause and fix>. +== Additional resources -== Related information +// REQUIRED. Include links to related concepts, procedures, and reference pages. -* xref:<component>:<module>/page.adoc[Link text] +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_blank] diff --git a/modules/_templates/reference.adoc b/modules/_templates/reference.adoc index a1b1ab16c..0f6195c42 100644 --- a/modules/_templates/reference.adoc +++ b/modules/_templates/reference.adoc @@ -3,16 +3,15 @@ :toclevels: 1 // Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. -:page-title: <Title — must match the = Title above> -:page-description: <One sentence: what this reference documents and who uses it.> -:keywords: <comma-separated terms for search indexing, for example, "REST API, parameters, endpoints, reference"> -:page-pageid: +:page-title: <Title text for the page> +:page-description: <State the purpose and brief summary of the contents of the reference document> +:keywords: <comma-separated terms for search indexing, for example, "REST API endpoint, parameters"> +:page-pageid: <Required attribute for ThoughtSpot Embedded and developer documentation. Add a unique ID for this page. For example, "Variable API reference".> :page-type: reference -:page-role: +:page-role: <Optional> :product-version: <version> -:jira-ref: <DOC-XXXX> -// author: -// last-updated: +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> //// TEMPLATE GUIDE @@ -160,45 +159,13 @@ curl -X POST \ } ---- -=== Response codes +=== API response Response codes -// REQUIRED for REST API reference. - -[cols="1,1,3", options="header"] -|=== -|Code |Status |Description - -|200 -|Success -|Request completed. Returns the response object described above. - -|400 -|Bad request -|Invalid parameters. Verify required fields and data types. - -|401 -|Unauthorized -|Authentication failed. Check your bearer token or API credentials. - -|403 -|Forbidden -|Insufficient permissions. Verify the user role required for this operation. - -|500 -|Internal server error -|Contact ThoughtSpot Support if the error persists. - -|=== - -// ───────────────────────────────────────────────────────────────────────────── -// END ENDPOINT / ATTRIBUTE BLOCK — copy the block above for additional endpoints -// ───────────────────────────────────────────────────────────────────────────── +// REQUIRED for REST API reference. Specify API response and include additional details as needed. -== Related information +== Additional resources -// REQUIRED. -// Link to related how-to and concept pages. -// "Related information" is the standard heading — do not use "Additional resources" or "See also". +// REQUIRED. Include links to related concepts, procedures, and reference pages. -* xref:<module>/procedure-page.adoc[How to <use this API>] -* xref:<module>/concept-page.adoc[Related concept] +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_blank] \ No newline at end of file diff --git a/modules/_templates/release-notes.adoc b/modules/_templates/release-notes.adoc index 80a092a0d..12f494c90 100644 --- a/modules/_templates/release-notes.adoc +++ b/modules/_templates/release-notes.adoc @@ -1,13 +1,14 @@ = Release notes: <Product> <Version or Month Year> :toc: true :toclevels: 1 -:page-title: <Title — must match the = Title above> +:page-title: <Title text for the page> :page-description: <One sentence: summary of what is new or changed in this release.> :keywords: <comma-separated terms for search indexing, for example, "release notes, changelog, new features"> :page-type: release-note :page-role: :product-version: <version> -:jira-ref: <DOC-XXXX> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> //// TEMPLATE GUIDE @@ -29,7 +30,7 @@ Section labels: Tags (column cell — use in the first column of the change table): [tag greenBackground]#NEW FEATURE# - [tag greenBackground]#IMPROVEMENT# + [tag greenBackground]#ENHANCEMENTT# [tag redBackground]#DEPRECATED# [tag redBackground]#BUG FIX# @@ -43,7 +44,7 @@ Inline badges (append after a feature name or inside a description): Format notes: - Use [discrete] before ==== headings inside table cells to suppress TOC entries. - Separate entries within the same cell with a horizontal rule: --- - - Each JIRA reference appears in parentheses at the end: (DOC-XXXX) + - Each JIRA reference appears in parentheses at the end: (SCAL-XXXXXX) - Use `*` bold for version labels and metadata lines inside cells. - Link to full documentation using xref once the target page is published. //// @@ -84,19 +85,19 @@ Description of the second new feature. // ── IMPROVEMENTS ────────────────────────────────────────────────────────────── |[tag greenBackground]#IMPROVEMENT# a| -* Brief description of the improvement. (DOC-XXXX) -* Brief description of another improvement. (DOC-XXXX) +* Brief description of the improvement. (SCAL-XXXXXX) +* Brief description of another improvement. (SCAL-XXXXXX) // ── DEPRECATIONS ────────────────────────────────────────────────────────────── |[tag redBackground]#DEPRECATED# a| -* `<deprecated_item>` — deprecated in this release. Use `<replacement>` instead. (DOC-XXXX) +* `<deprecated_item>` — deprecated in this release. Use `<replacement>` instead. (SCAL-XXXXXX) // ── BUG FIXES ───────────────────────────────────────────────────────────────── |[tag redBackground]#BUG FIX# a| -* Brief description of what was broken and what was fixed. (DOC-XXXX) -* Brief description of another bug fix. (DOC-XXXX) +* Brief description of what was broken and what was fixed. (SCAL-XXXXXX) +* Brief description of another bug fix. (SCAL-XXXXXX) |==== @@ -105,10 +106,9 @@ Description of the second new feature. // Document breaking changes, configuration updates, or migration steps required. // Reference specific API endpoints, SDK methods, or config keys by name. -// TODO: verify all migration steps with engineering before publishing. == Known issues // OPTIONAL but recommended. Describe open issues in this release and any workaround. -* Description of the known issue. Workaround: <steps or link>. (DOC-XXXX) +* Description of the known issue. Workaround: <steps or link>. (SCAL-XXXXXX) diff --git a/modules/_templates/troubleshooting.adoc b/modules/_templates/troubleshooting.adoc index 6ec2b685b..227b7ab84 100644 --- a/modules/_templates/troubleshooting.adoc +++ b/modules/_templates/troubleshooting.adoc @@ -1,6 +1,8 @@ = <Title: Noun phrase describing the problem area, for example, "Troubleshoot Authentication Errors"> :toc: true :toclevels: 1 + +<Title text for the page> :page-pageid: :page-type: troubleshooting :page-role: @@ -85,6 +87,9 @@ # Example command to collect diagnostic output ---- -== Related information +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. -* xref:<component>:<module>/page.adoc[Link text] +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_bl \ No newline at end of file diff --git a/modules/_templates/tutorial.adoc b/modules/_templates/tutorial.adoc deleted file mode 100644 index a1d011266..000000000 --- a/modules/_templates/tutorial.adoc +++ /dev/null @@ -1,229 +0,0 @@ -= <Title: Action-oriented phrase describing what the user builds, -for example, "Build a Real-Time Dashboard Using the <Product> API"> -:toc: true -:toclevels: 1 -:page-pageid: -:page-type: tutorial -:page-role: -:product-version: <version> -:jira-ref: <DOC-XXXX> -// author: -// last-reviewed: - -// 2-3 sentences covering: -// - What the user will build or accomplish -// - What they will learn along the way -// - Estimated time to complete -// Example: "In this tutorial, you build a <thing> using <Product>. -// You learn how to <skill 1>, <skill 2>, and <skill 3>. -// Estimated time: 30 minutes." - -== Learning objectives - -// List what the user will be able to do after completing this tutorial. -// Use "After completing this tutorial, you will be able to:" as the lead. -// Write each objective as a verb phrase. - -After completing this tutorial, you will be able to: - -* <Verb phrase, for example, "Configure a <Product> connection using OAuth 2.0"> -* <Verb phrase> -* <Verb phrase> - -== Before you begin - -// List prerequisites with enough specificity that the user can -// self-qualify before investing time in the tutorial. - -* *Experience level*: <for example, "Familiarity with REST APIs and JSON"> -* *<Tool or dependency>*: version <X.X> or later installed and configured. - See xref:<component>:<module>/page.adoc[Install <Tool>]. -* *<Account or access>*: <describe what is needed and how to obtain it> -* *Completed*: xref:<component>:<module>/quickstart.adoc[Get Started with <Product>] -// TODO: verify prerequisites with engineering - -== Overview - -// Optional but recommended for tutorials over 20 minutes. -// Briefly describe the architecture, workflow, or scenario the -// user is working through, so they understand the big picture -// before diving into steps. A diagram (image::) works well here. - -In this tutorial, you: - -. <High-level phase 1, for example, "Set up the project structure"> -. <High-level phase 2, for example, "Configure authentication"> -. <High-level phase 3, for example, "Implement the core logic"> -. <High-level phase 4, for example, "Test and verify the result"> - -== Part 1: <Phase title, for example, "Set up the project"> - -// Tutorials are longer than procedures. Use H2 parts to divide -// the work into phases the user can pause and resume between. -// Each part should produce a verifiable intermediate result. - -<Context sentence: explain what this part accomplishes and why -it comes first.> - -. Action one. -+ -[source,bash] ----- -# example command ----- - -. Action two. -+ -[source,<language>] ----- -// example code ----- - -. Action three. - -=== Checkpoint - -// End each part with a checkpoint so the user can verify their -// work before continuing. A failed checkpoint at part 2 is much -// easier to recover from than discovering an error at part 5. - -Verify that <expected state>: - -[source,bash] ----- -# verification command ----- - -Expected output: - ----- -<expected output> ----- - -If you see <unexpected output>, see <<troubleshooting>> at the end -of this tutorial. - -== Part 2: <Phase title> - -<Context sentence.> - -. Action one. -+ -[source,<language>] ----- -// example code ----- - -. Action two. - -. Action three. -+ -[source,<language>] ----- -// example code ----- - -=== Checkpoint - -Verify that <expected state>: - -[source,bash] ----- -# verification command ----- - -// TODO: verify steps and expected output with engineering - -== Part 3: <Phase title> - -<Context sentence.> - -. Action one. -. Action two. -. Action three. - -=== Checkpoint - -Verify that <expected state>: - -[source,bash] ----- -# verification command ----- - -== Part 4: <Phase title> - -<Context sentence.> - -. Action one. -. Action two. -. Action three. - -=== Checkpoint - -Verify that <expected state>: - -[source,bash] ----- -# verification command ----- - -== Summary - -// Briefly recap what the user built and what they learned. -// Reinforce the learning objectives from the top of the page. - -In this tutorial, you: - -* <Past-tense summary of what was built or configured> -* <Past-tense summary of a key skill practiced> -* <Past-tense summary of a key concept applied> - -== Clean up - -// Optional but important for tutorials involving cloud resources, -// paid services, or system changes the user may want to reverse. - -To remove the resources created in this tutorial: - -. Step one. -. Step two. -+ -[source,bash] ----- -# cleanup command ----- - -== Next steps - -// Point the user toward the logical next tutorial, a deeper -// feature guide, or the full reference documentation. - -* xref:<component>:<module>/page.adoc[<Next tutorial in the series>] -* xref:<component>:<module>/page.adoc[<Deeper feature guide>] -* xref:<component>:<module>/page.adoc[<Related best practices>] - -[#troubleshooting] -== Troubleshooting - -// Cover issues specific to this tutorial — configuration mistakes, -// environment differences, and common errors at checkpoint steps. - -[cols="1,2", options="header"] -|=== -|Symptom |Solution - -|<Error message or unexpected behavior> -|<Cause and fix> - -|<Error message or unexpected behavior> -|<Cause and fix> - -|=== - -For general troubleshooting, see -xref:<component>:<module>/troubleshooting.adoc[Troubleshoot <Product>]. - -== Related information - -* xref:<component>:<module>/page.adoc[Link text] From 0ba2d7e9380377f054aeacf7c8e488666e97eb33 Mon Sep 17 00:00:00 2001 From: ShashiSubramanya <shashikala.subramanya@thoughtspot.com> Date: Thu, 28 May 2026 15:15:45 +0530 Subject: [PATCH 5/5] vale update --- .github/workflows/vale.yml | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml index b469a474d..521816585 100644 --- a/.github/workflows/vale.yml +++ b/.github/workflows/vale.yml @@ -14,14 +14,19 @@ jobs: - name: Checkout uses: actions/checkout@v4 + - name: Install AsciiDoc dependencies + run: sudo apt-get install -y asciidoctor + - name: Run Vale uses: errata-ai/vale-action@v2 with: # CI config: ts-docs rules only, error level gate. # Does not run vale sync — no package downloads needed. - config: .vale-ci.ini - # Check only files changed in this PR. - files: changed + vale_flags: "--config=.vale-ci.ini" + # Run on all files; filter_mode=added limits PR annotations + # to lines added/changed in this PR only. + files: all + filter_mode: added # Fail the build on errors (merge conflict markers, # unfilled placeholders). Warnings are reported but # do not block the PR.