Skip to content

Commit 8a847ab

Browse files
ShashiSubramanyaShashiSubramanya
committed
edits
1 parent 72800c3 commit 8a847ab

4 files changed

Lines changed: 490 additions & 44 deletions

File tree

‎modules/_templates/concept.adoc‎

Lines changed: 98 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,121 @@
11
= <Title: Noun phrase describing the concept>
22
:toc: true
33
:toclevels: 1
4-
:page-pageid:
4+
5+
:page-title: <Title — must match the = Title above>
6+
:page-description: <One sentence: what this page covers and why it matters to the reader.>
7+
:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.>
8+
:keywords: <comma-separated terms for search indexing, e.g. "authentication, SSO, SAML, login">
59
:page-type: concept
610
:page-role:
711
:product-version: <version>
812
:jira-ref: <DOC-XXXX>
13+
914
// author:
1015
// last-reviewed:
1116

12-
// 1-2 sentence lead: what this concept is and why it matters.
17+
// REQUIRED: 1-2 sentence lead — what this concept is and why it matters to developers or administrators.
18+
19+
////
20+
TEMPLATE GUIDE
21+
==============
22+
How to use this template:
23+
1. Copy this file from modules/_templates/concept.adoc.
24+
2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "embed-sso-overview.adoc").
25+
3. Place the file in modules/ROOT/pages/.
26+
4. If this page will be included as a partial inside another page (via include::),
27+
remove all front-matter attributes — partials do not need them.
28+
29+
Use this template for pages that explain WHAT something is or HOW it works.
30+
Do NOT include step-by-step instructions here — link to a procedure page instead.
31+
32+
Section labels:
33+
REQUIRED — must be present on every page of this type
34+
RECOMMENDED — include unless there is a clear reason not to
35+
OPTIONAL — include only when relevant to the topic
36+
37+
Style elements you can use:
38+
Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION]
39+
Images : image::<path>[alt text]
40+
Tables : [cols="...", options="header"] |=== ... |===
41+
Code blocks : [source,JavaScript] ---- ... ----
42+
Inline badge : [beta betaBackground]^Beta^
43+
Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated#
44+
[.version-badge.breaking]#Breaking# [.version-badge.fixed]#Fixed#
45+
////
1346
1447
== How <concept> works
1548
16-
// Explanation. Use diagrams (image::) where spatial relationships matter.
17-
// Avoid procedure steps here — link to procedure pages instead.
49+
// REQUIRED.
50+
// Explain the concept clearly. Avoid procedure steps — link to procedure pages instead.
51+
// Use plain language; define acronyms on first use.
52+
//
53+
// Add a diagram or screenshot if spatial relationships or architecture matter:
54+
// image::./images/<diagram-filename>.png[Alt text describing the diagram]
55+
//
56+
// Example:
57+
// image::./images/embed-architecture.png[ThoughtSpot embedded architecture overview showing the SDK, REST API, and host application layers]
58+
//
59+
// Use admonitions to highlight key information:
60+
// [NOTE]
61+
// ====
62+
// Text for a general note or clarification.
63+
// ====
64+
//
65+
// [IMPORTANT]
66+
// ====
67+
// Text for a critical constraint the reader must know before using this feature.
68+
// ====
1869
1970
== Key components
2071
21-
// Optional. Use a definition list for named parts:
22-
Component name::
72+
// OPTIONAL.
73+
// Use a definition list for named parts or actors in the system:
74+
75+
Component A::
76+
Description of what it does and its role in the system.
77+
78+
Component B::
2379
Description of what it does.
2480
81+
// OPTIONAL: Add a comparison matrix when the concept involves multiple options or variants
82+
// that readers commonly need to choose between:
83+
//
84+
// [cols="1,1,1,1", options="header"]
85+
// |===
86+
// |Option |Best for |Authentication |Notes
87+
// |REST API v2 |New integrations |Bearer token |Recommended
88+
// |REST API v1 |Legacy systems |Basic auth |Migrate to v2 when possible
89+
// |Visual Embed SDK |Embedded UI |Trusted auth |TypeScript support
90+
// |===
91+
2592
== Limitations and constraints
2693
27-
// Known limitations, version-specific behaviour, or edge cases.
28-
// TODO: verify with engineering
94+
// RECOMMENDED.
95+
// List known limitations, version-specific behaviour, or edge cases the reader should know.
96+
// Use admonitions for critical constraints:
97+
//
98+
// [IMPORTANT]
99+
// ====
100+
// This feature requires ThoughtSpot Cloud <version> or later.
101+
// ====
102+
//
103+
// [NOTE]
104+
// ====
105+
// Behaviour changed in <version>. If you are on an earlier version, see xref:...[]
106+
// ====
107+
//
108+
// [WARNING]
109+
// ====
110+
// Enabling this setting affects all users in the org. Confirm with your administrator before proceeding.
111+
// ====
112+
113+
*
29114
30115
== Related information
31116
32-
* xref:<component>:<module>/page.adoc[Link text]
117+
// REQUIRED.
118+
// Link to related concept, procedure, and reference pages.
119+
// "Related information" is the standard heading — do not use "Additional resources" or "See also".
120+
121+
* xref:<module>/page.adoc[Link text]

‎modules/_templates/procedure.adoc‎

Lines changed: 119 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,151 @@
11
= <Title: Verb + Object, e.g. "Configure Single Sign-On">
22
:toc: true
33
:toclevels: 1
4-
:page-pageid:
4+
5+
:page-title: <Title — must match the = Title above>
6+
:page-description: <One sentence: what this procedure does and who it is for.>
7+
:page-pageid: <Add a unique ID for this page, e.g. "embed-sdk-concepts". Required for developer documentation.>
58
:page-type: procedure
9+
:keywords: <comma-separated terms for search indexing, e.g. "configure, SSO, SAML, setup">
610
:page-role:
711
:product-version: <version>
812
:jira-ref: <DOC-XXXX>
913
// author:
1014
// last-reviewed:
1115

16+
////
17+
TEMPLATE GUIDE
18+
==============
19+
How to use this template:
20+
1. Copy this file from modules/_templates/procedure.adoc.
21+
2. Rename the copy to <file-name>.adoc (lowercase, hyphen-separated, e.g. "configure-saml-sso.adoc").
22+
3. Place the file in modules/ROOT/pages/.
23+
4. If this page will be included as a partial inside another page (via include::),
24+
remove all front-matter attributes — partials do not need them.
25+
26+
Use this template for pages that describe HOW TO DO something — a sequence of steps
27+
the reader must follow to achieve a specific outcome.
28+
Do NOT explain background theory here — link to a concept page for that.
29+
30+
Section labels:
31+
REQUIRED — must be present on every page of this type
32+
RECOMMENDED — include unless there is a clear reason not to
33+
OPTIONAL — include only when relevant to the topic
34+
35+
Code samples:
36+
SDK procedures : JavaScript or TypeScript code sample is REQUIRED.
37+
REST API procedures: cURL code sample is REQUIRED. JSON request/response is REQUIRED.
38+
UI-only procedures : screenshots are RECOMMENDED (use image:: after the relevant step).
39+
40+
Style elements you can use:
41+
Admonitions : [NOTE], [TIP], [IMPORTANT], [WARNING], [CAUTION]
42+
Images : image::<path>[alt text]
43+
Code blocks : [source,JavaScript] / [source,TypeScript] / [source,cURL] / [source,JSON]
44+
Inline badge : [beta betaBackground]^Beta^
45+
Version badge: [.version-badge.new]#New# [.version-badge.deprecated]#Deprecated#
46+
[.version-badge.breaking]#Breaking#
47+
////
48+
1249
== Overview
1350
14-
// 1-2 sentences: what this procedure accomplishes and who it is for.
15-
// TODO: verify with engineering
51+
// REQUIRED: 1-2 sentences — what this procedure accomplishes and who it is for.
52+
// Mention the product area and the role of the reader (developer, administrator, etc.).
53+
// TODO: verify scope with engineering
54+
//
55+
// OPTIONAL: Add a workflow diagram or screenshot of the starting UI state if it helps
56+
// the reader orient themselves before starting:
57+
// image::./images/<workflow-diagram>.png[Workflow overview diagram]
1658
1759
== Before you begin
1860
19-
// Prerequisites as a list. Use "You must" or "You need" for each.
20-
*
21-
*
61+
// REQUIRED if there are prerequisites. Use "You must" or "You need" for each item.
62+
// Remove this section only if there are genuinely no prerequisites.
63+
64+
* You must have <role or permission, e.g. "Developer or Administrator privilege">.
65+
* You need access to <system or resource, e.g. "a ThoughtSpot Cloud instance with the Embed feature enabled">.
66+
* <Any additional prerequisite.>
2267
2368
== Procedure
2469
25-
. Step one. Include the exact command or UI action.
70+
// REQUIRED. Use numbered steps. Each step must describe exactly one action.
71+
// Include the exact command, UI label, menu path, or code for each step.
72+
// Add a `+` continuation after a step to attach a code block or image to it.
73+
74+
. Step one. Describe the exact UI action or navigation path.
75+
+
76+
// OPTIONAL: Screenshot showing the UI state after this step:
77+
// image::./images/<step1-screenshot>.png[Description of what to see after step 1]
78+
79+
. Step two. For SDK procedures, provide a complete, runnable code sample — REQUIRED.
2680
+
27-
[source,bash]
81+
[source,JavaScript]
2882
----
29-
# example command here
83+
import { LiveboardEmbed, AuthType, init } from '@thoughtspot/visual-embed-sdk';
84+
85+
init({
86+
thoughtSpotHost: 'https://<your-instance>.thoughtspot.cloud',
87+
authType: AuthType.TrustedAuthToken,
88+
username: '<username>',
89+
getAuthToken: () => getTokenFromYourServer(),
90+
});
91+
92+
const embed = new LiveboardEmbed('#embed-container', {
93+
liveboardId: '<liveboard-GUID>',
94+
});
95+
embed.render();
3096
----
97+
+
98+
[NOTE]
99+
====
100+
Replace `<your-instance>` with your ThoughtSpot Cloud hostname and `<liveboard-GUID>` with the ID of the Liveboard you want to embed.
101+
====
31102
32-
. Step two.
103+
. Step three. For REST API procedures, provide a cURL request — REQUIRED.
104+
+
105+
[source,cURL]
106+
----
107+
curl -X POST \
108+
'https://<your-instance>.thoughtspot.cloud/api/rest/2.0/<endpoint>' \
109+
-H 'Authorization: Bearer <token>' \
110+
-H 'Content-Type: application/json' \
111+
-d '{
112+
"param": "value"
113+
}'
114+
----
115+
+
116+
// OPTIONAL: Show the expected JSON response inline:
117+
// [source,JSON]
118+
// ----
119+
// {
120+
// "field": "value"
121+
// }
122+
// ----
33123
34-
. Step three.
124+
// OPTIONAL: Add a WARNING or NOTE for common pitfalls at the end of the procedure.
125+
// [WARNING]
126+
// ====
127+
// If you see <error>, verify that <condition> before retrying.
128+
// ====
35129
36130
== Result
37131
38-
// What the user should see or be able to do after completing the procedure.
132+
// REQUIRED. Describe what the user should see or be able to do after completing the procedure.
133+
// Be specific — name the UI element, API response, or behaviour that confirms success.
134+
//
135+
// OPTIONAL: Screenshot of the expected result:
136+
// image::./images/<result-screenshot>.png[Expected result after completing the procedure]
39137
40138
== Next steps
41139
42-
// Optional. Link to related procedures or concepts.
140+
// OPTIONAL. Link to the next logical task or a related procedure.
141+
142+
* xref:<module>/next-procedure.adoc[Next task name]
43143
44144
== Related information
45145
46-
* xref:<component>:<module>/page.adoc[Link text]
146+
// REQUIRED.
147+
// Link to related concept and reference pages.
148+
// "Related information" is the standard heading — do not use "Additional resources" or "See also".
149+
150+
* xref:<module>/concept-page.adoc[Related concept]
151+
* xref:<module>/reference-page.adoc[API reference]

0 commit comments

Comments
 (0)