diff --git a/.github/workflows/vale.yml b/.github/workflows/vale.yml new file mode 100644 index 000000000..521816585 --- /dev/null +++ b/.github/workflows/vale.yml @@ -0,0 +1,36 @@ +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: 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. + 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. + 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 --------------------------- + - '' + - '' + - '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. + - '' + - '' + - '' + - 'your-instance' + - 'liveboard-GUID' + - '' + - '' + - '' + - '' + - '' + + # ---- Add your own template placeholder patterns --------- + # - '' + + # ---- 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/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/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..7229db838 --- /dev/null +++ b/modules/_templates/best-practices.adoc @@ -0,0 +1,81 @@ += "> +:toc: true +:toclevels: 1 +// Adjust toclevels if you have many sections, but 1-2 levels is usually sufficient for reference pages. + +:page-title: +: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: <Optional> +:product-version: <version> +:jira-ref: <SCAL-XXXXXX> +// 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 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.> + +// 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 new file mode 100644 index 000000000..6995cea60 --- /dev/null +++ b/modules/_templates/concept.adoc @@ -0,0 +1,124 @@ += <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 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, "spotter-embed-overview"> +:keywords: <comma-separated terms for search indexing, for example, "authentication, SSO, SAML, login"> +:page-role: <Optional> +:product-version: <version> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +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, 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. + +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# +============== +//// + + +// 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. +// Use plain language; define acronyms on first use. +// +// Add a diagram or screenshot if spatial relationships or architecture matter: +// 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. +// ==== +// +// [IMPORTANT] +// ==== +// Text for a critical constraint the reader must know before using this feature. +// ==== + +== Key components + +// 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 + +// RECOMMENDED. +// List known limitations, version-specific behavior, or edge cases the reader should know. +* <Known limitation or constraint.> + +// Use admonitions for critical constraints: +// +// [IMPORTANT] +// ==== +// This feature requires ThoughtSpot Cloud <version> or later. +// ==== +// +// [NOTE] +// ==== +// Behavior 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. +// ==== + +== Additional resources + +// REQUIRED. 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/faqs.adoc b/modules/_templates/faqs.adoc new file mode 100644 index 000000000..c5a1803f7 --- /dev/null +++ b/modules/_templates/faqs.adoc @@ -0,0 +1,63 @@ += <Title: Noun phrase, for example, "Frequently Asked Questions: Authentication"> +:toc: true +:toclevels: 1 + + +: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: <Optional> +:product-version: <version> +: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. + +== <Information category. For example, Embed authentication> + +=== <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. + +=== <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 + +// 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 new file mode 100644 index 000000000..f75e0f255 --- /dev/null +++ b/modules/_templates/procedure.adoc @@ -0,0 +1,129 @@ += <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 text for the page> +:page-description: <One sentence: what this procedure 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, "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: <SCAL-XXXXXX> +// 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, 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. + +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 + +// REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for. +// 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 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>. + +== <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. +// 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] +// For SDK procedures, a code sample is REQUIRED. Use the following format for code samples: + +[source,JavaScript] +---- +<code sample> +---- + +// For REST API procedures, document the required parameters and provide request and response 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": "value" + }' +---- + +// OPTIONAL: Show the expected JSON response inline: +// [source,JSON] +// ---- +// { +// "field": "value" +// } +// ---- + +// 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 + +// REQUIRED. Describe what the user should see or be able to do after completing the procedure. +// Be specific. Specify the name the UI element, API response, or behavior that confirms success. +// OPTIONAL: Screenshot of the expected result: + +== Next steps + +// OPTIONAL. Link to the next logical task or a related procedure. +// * xref:next-procedure.adoc[Next task name] + + +== Additional resources + +// REQUIRED. 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/quickstart.adoc b/modules/_templates/quickstart.adoc new file mode 100644 index 000000000..a9cc206f9 --- /dev/null +++ b/modules/_templates/quickstart.adoc @@ -0,0 +1,104 @@ += Get Started with <Product or Feature Name> +:toc: true +:toclevels: 1 +// 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: <SCAL-XXXXXX> +// last-reviewed: + +// 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. + + +== 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. + +. 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. + + +== 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 <feature> running, you can: + +* 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. + +* *<Issue*: <state the issue, cause, and fix/workaround>. +* *<Issue*: <state the issue, cause, and fix/workaround>. + +// Link to the full troubleshooting page if one exists. + +== Additional resources + +// REQUIRED. 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/reference.adoc b/modules/_templates/reference.adoc new file mode 100644 index 000000000..0f6195c42 --- /dev/null +++ b/modules/_templates/reference.adoc @@ -0,0 +1,171 @@ += <Title: Noun phrase, for example, "Liveboard report API reference"> +:toc: true +:toclevels: 1 +// 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: <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: <Optional> +:product-version: <version> +:jira-ref: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +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, 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 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 + 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. + + +// ───────────────────────────────────────────────────────────────────────────── +// 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"] +|=== +|Parameter |Type |Required |Description + +|`param_name` +|string +|Yes +|Description of what this parameter does. Default: none. + +|`optional_param` +|boolean +|No +|Optional flag. Default: `false`. + +|=== + +// 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` — behavior changed in vX.X. + +=== Example request + +// REQUIRED. Provide a complete, working example. +// For SDK reference: + +[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] +---- +{ + "field": "value", + "nested": { + "key": "value" + } +} +---- + +=== API response Response codes + +// REQUIRED for REST API reference. Specify API response and include additional details as needed. + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* 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 new file mode 100644 index 000000000..12f494c90 --- /dev/null +++ b/modules/_templates/release-notes.adoc @@ -0,0 +1,114 @@ += Release notes: <Product> <Version or Month Year> +:toc: true +:toclevels: 1 +: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: <SCAL-XXXXXX> +// last-reviewed: <Optional> + +//// +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, 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. + +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. + +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 + +Tags (column cell — use in the first column of the change table): + [tag greenBackground]#NEW FEATURE# + [tag greenBackground]#ENHANCEMENTT# + [tag redBackground]#DEPRECATED# + [tag redBackground]#BUG FIX# + +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 + +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: (SCAL-XXXXXX) + - Use `*` bold for version labels and metadata lines inside cells. + - Link to full documentation using xref once the target page is published. +//// + +// REQUIRED: One sentence stating the release scope and any critical headline. +This release includes updates to <product area, for example, "the Visual Embed SDK and embed APIs">. + +// REQUIRED: Release metadata block. +*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 + +// 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| + +* 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. (SCAL-XXXXXX) + +// ── BUG FIXES ───────────────────────────────────────────────────────────────── +|[tag redBackground]#BUG FIX# a| + +* Brief description of what was broken and what was fixed. (SCAL-XXXXXX) +* Brief description of another bug fix. (SCAL-XXXXXX) + +|==== + +// REQUIRED only when this release includes breaking changes or migration steps. +== Upgrade notes + +// Document breaking changes, configuration updates, or migration steps required. +// Reference specific API endpoints, SDK methods, or config keys by name. + +== Known issues + +// OPTIONAL but recommended. Describe open issues in this release and any workaround. + +* Description of the known issue. Workaround: <steps or link>. (SCAL-XXXXXX) diff --git a/modules/_templates/troubleshooting.adoc b/modules/_templates/troubleshooting.adoc new file mode 100644 index 000000000..227b7ab84 --- /dev/null +++ b/modules/_templates/troubleshooting.adoc @@ -0,0 +1,95 @@ += <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: +: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 +---- + +== Additional resources + +// REQUIRED. Include links to related concepts, procedures, and reference pages. + +//* xref:page.adoc[Link text]. +//* link:<URL>[Link text, window=_bl \ No newline at end of file