Skip to content

Commit 7eb5b3f

Browse files
laubailaubai
committed
OSDOCS-7862 Adding additional resources to example and resolving rebase from Janelle's work on the template
1 parent e4b58a6 commit 7eb5b3f

File tree

1 file changed

+248
-31
lines changed

1 file changed

+248
-31
lines changed

‎cloud_experts_tutorials/cloud-experts-template-tutorial.adoc

Lines changed: 248 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,18 @@
1+
//Duplicate this file and use it as a template to write your content.
2+
//Look for TODO statements and angle brackets to identify content to add or replace.
3+
4+
// Basic document metadata
5+
// TODO: replace anything in angle brackets in this metadata block
16
:_content-type: ASSEMBLY
27
[id=“cloud-experts-<topic>-tutorial”]
38
= Tutorial: <Topic>
49
include::_attributes/attributes-openshift-dedicated.adoc[]
510
:context: cloud-experts-<topic>-tutorial
611

12+
//This automatically adds a table of contents so readers can jump to a specific heading.
713
toc::[]
814

15+
//TODO: The following block must remain commented out, but add your name to the authors list in whatever format you want to be publicly visible in the openshift-docs repo.
916
//Mobb content metadata
1017
//Brought into ROSA product docs 2023-09-18
1118
//---
@@ -17,62 +24,272 @@ toc::[]
1724
// - <author>
1825
//---
1926

20-
Introductory text.
27+
// Docs will remove this support statement once this content has gone through regular QE validation.
28+
// TODO: IF YOU UPDATED THIS DOCUMENT AND THIS STATEMENT IS COMMENTED OUT, make sure you uncomment it again so QE can review your updates.
29+
include::snippets/mobb-support-statement.adoc[leveloffset=+1]
30+
31+
//TODO: Write a few sentences about what the people who use this doc want to accomplish and what that might let them do.
32+
Introductory sentence or two about this whole file and why a customer might want to follow these steps.
33+
34+
//TODO: Write up the information you want to publish for customers.
35+
//This documentation uses basic asciidoc syntax.
36+
37+
//TODO: replace anything in angle brackets and add your content below
38+
[id='cloud-experts-<topic>-tutorial-<subsection1>']
39+
== <Subsection 1>
40+
41+
Introductory sentence about the purpose of this section.
42+
43+
Steps or information that the customer should follow.
44+
45+
Check out the syntax guide below for examples of what you can add here.
46+
47+
//TODO: replace anything in angle brackets and add your content below
48+
[id='cloud-experts-<topic>-tutorial-<subsection2>']
49+
== <Subsection 2>
50+
51+
Introductory sentence about the purpose of this section.
52+
53+
Steps or information that a customer should follow.
54+
55+
Check out the syntax guide below for examples of what you can add here.
56+
57+
//TODO: Provide links to any next steps or additional information the user is likely to want at this point.
58+
//TODO: If no other resources are likely to be needed, just delete this block.
59+
[id='cloud-experts-<topic>-tutorial-additional-resources']
60+
== Additional resources
61+
* link:https://cloud.redhat.com/experts/rosa/verify-permissions[Verify required permissions for a ROSA STS deployment]
62+
* link:https://cloud.redhat.com/experts/rosa/ecr[Configure a ROSA cluster to pull images from AWS Elastic Container Registry]
63+
64+
//TODO: When you are finished writing your tutorial, delete everything below this line.
65+
// These are just some basic syntax examples so you can copy and paste easily.
66+
== AsciiDoc Syntax Basics
67+
68+
For more information, refer to link:https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer's Guide]
69+
70+
=== Headings
71+
72+
To add a heading, use equals signs at the beginning of the line:
73+
74+
[source]
75+
----
76+
== Second level heading text
77+
=== Third level heading text
78+
----
79+
80+
Up to 5 levels of heading are available, but this usually won't be required.
81+
82+
.Block element heading
83+
You can also add a small header to a block element by adding a full-stop at the start of the line. Do not add a space or this will become an ordered list item.
84+
85+
[source]
86+
----
87+
.Block element heading
88+
----
89+
90+
=== Paragraphs, links, and inline elements
91+
92+
A paragraph is just a plain line of text like this.
93+
A single line break will be rendered as part of the same paragraph.
94+
95+
A double line break will be rendered as a separate paragraph.
96+
97+
You can _emphasize_ or *strengthen* text in a paragraph, or add a link to a link:http://www.redhat.com[Red Hat website].
98+
99+
[source]
100+
----
101+
You can _emphasize_ or *strengthen* text in a paragraph, or add a link to a link:http://www.redhat.com[Red Hat website].
102+
----
103+
104+
Link to non-Red Hat websites if necessary, but remember they won't necessarily open in a new tab, and might lead users away from your document.
105+
106+
=== Lists
107+
108+
Unordered lists use asterisks followed by a space:
109+
110+
.My unordered list
111+
* First level list item
112+
** Use multiple asterisks to indent second level list items
113+
* Another first level list item
114+
115+
[source]
116+
----
117+
.My unordered list
118+
* First level list item
119+
** Use multiple asterisks to indent second level list items
120+
* Another first level list item
121+
----
122+
123+
Ordered lists use full stops followed by a space:
124+
125+
.My ordered list
126+
. Step one
127+
.. Step 1.a.
128+
. Step two
129+
130+
[source]
131+
----
132+
.My ordered list
133+
. Step one
134+
.. Step 1.a.
135+
. Step two
136+
----
137+
138+
You can also use two colons to get a term and definition list:
139+
140+
.Important definitions
141+
term:: definition goes here
142+
cat:: A cute and cuddly carnivorous companion animal with hidden foot knives.
143+
dog:: A cute and cuddly omnivorous companion animal with clearly visible foot knives.
144+
145+
[source]
146+
----
147+
.Important definitions
148+
term:: definition goes here
149+
cat:: A cute and cuddly carnivorous companion animal with hidden foot knives.
150+
dog:: A cute and cuddly omnivorous companion animal with clearly visible foot knives.
151+
----
152+
153+
=== Code
154+
155+
You can use `backticks` to indicate a literal value inline, but for commands, code, and terminal output you want a code block:
156+
157+
[source,terminal]
158+
----
159+
$ rosa version
160+
1.2.23
161+
I: There is a newer release version '1.2.26', please consider updating: https://mirror.openshift.com/pub/openshift-v4/clients/rosa/latest/
162+
----
163+
164+
[source]
165+
------
166+
[source,terminal]
167+
----
168+
$ rosa version
169+
1.2.23
170+
I: There is a newer release version '1.2.26', please consider updating: https://mirror.openshift.com/pub/openshift-v4/clients/rosa/latest/
171+
----
172+
------
173+
174+
The `[source]` part ahead of the code block specifies the kind of code in the block, and enables syntax highlighting based on the language provided after the comma.
175+
21176

22-
== <Heading 2>
177+
=== Tables
23178

24-
Paragraph text.
179+
Tables use a combination of pipes and equals signs for their basic structure. If you want to include more complex content, you can add an `a` before the pipe indicating the start of the complex cell, and use other kinds of asciidoc syntax in that cell as required.
25180

26-
image::<example-image>.png[<example image text>]
181+
.Tables need a title
182+
|===
183+
|Left column |Right column
184+
185+
| Row 1 left column cell
186+
| Row 1 right column cell
187+
188+
a| Row 2 left column cell
27189

28190
[NOTE]
29191
====
30-
Images need to be added to the OpenShift images folder to build in the content.
192+
With a note!
31193
====
32194

33-
=== <Heading 3>
195+
| Row 2 right column cell
34196

35-
.Prerequisites <formatting>
197+
|===
36198

37-
Here is the link formatting:
199+
[source]
200+
------
201+
.Tables need a title
202+
|===
203+
|Left column |Right column
38204
39-
* xref:../rosa_architecture/rosa-getting-support.adoc#rosa-getting-support[Sample cross reference]
40-
* link:<redhat.com>[External or hard link]
41-
+
42-
Example: link:https://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc Writer's Guide]
205+
| Row 1 left column cell
206+
| Row 1 right column cell
43207
44-
.Procedures <formatting>
208+
a| Row 2 left column cell
45209
46-
. <numbered step formatting>
47-
.. <numbered substep formatting>
210+
[NOTE]
211+
=====
212+
With a note!
213+
====
48214
49-
* <bullet formatting: use a bullet for single-step processes or non-numbered processes>
50-
** <bulleted substep formatting>
215+
| Row 2 right column cell
51216
52-
.Code <formatting>
217+
|===
218+
------
53219

54-
[source,terminal]
220+
=== Images
221+
222+
Place the image you want to use in the `cloud_experts_tutorials/images` sub-directory, and use only the file name in the `image::` block (not the relative path). For accessibility support, add a title for the image and describe the contents of the image. We recommend using PNG and SVG image formats.
223+
224+
.The perspectives menu in OpenShift Web Console
225+
image::web_console_perspectives.png[The perspectives menu in OpenShift Web Console showing the Developer and Administrator persoectives]
226+
227+
[source]
55228
----
56-
$ <sample-code-block>
229+
.The perspectives menu in OpenShift Web Console
230+
image::web_console_perspectives.png[The perspectives menu in OpenShift Web Console showing the Developer and Administrator persoectives]
57231
----
58232

59-
.Admonitions <formatting>
233+
=== Warnings and admonition blocks
234+
235+
If you want to highlight some information you can place it in a callout block.
236+
Only do this for important things a user might miss, or our users will start ignoring them.
237+
238+
[NOTE]
239+
====
240+
You can use other elements inside an admonition, but don't go overboard.
241+
We typically use three kinds:
242+
243+
* NOTE is for information that is useful, and can often be just a regular sentence instead.
244+
* IMPORTANT is for information that a customer should be aware of but won't cause serious problems if it's ignored.
245+
* WARNING is for information that a customer needs to obey to avoid data loss or other critical failures.
246+
====
247+
248+
[source]
249+
----
60250
61251
[NOTE]
62252
====
63-
<sample note formatting; you can use the following admonitions>
253+
You can use other elements inside an admonition, but don't go overboard.
254+
We typically use three kinds:
64255
65-
* NOTE
66-
* TIP
67-
* IMPORTANT
68-
* CAUTION
69-
* WARNING
256+
* NOTE is for information that is useful to know, and can often be just a regular sentence instead.
257+
* IMPORTANT is for information that a customer should be aware of but won't cause serious problems if it's ignored.
258+
* WARNING is for information that a customer needs to obey to avoid data loss or other critical failures.
70259
====
260+
----
71261

72-
.Punctuation <formatting>
262+
=== Combining block level elements
263+
264+
You can chain multiple block-level asciidoc elements together with the plus sign. You'll most often do this with steps and code blocks, so that the code block stays at the same indent level as the instruction text, for example:
265+
266+
. Open a terminal and log in to the ROSA CLI using your personal token:
267+
+
268+
[source,terminal]
269+
----
270+
$ rosa login --token=<your_token>
271+
----
73272

74-
* *Bold Text*
75-
* _Italicized Text_
76-
// Line comment
273+
. Check your ROSA CLI version:
274+
+
275+
[source,terminal]
276+
----
277+
$ rosa version
278+
----
77279

280+
[source]
281+
------
78282
283+
. Open a terminal and log in to the ROSA CLI using your personal token:
284+
+
285+
[source,terminal]
286+
----
287+
$ rosa login --token=<your_token>
288+
----
289+
. Check your ROSA CLI version:
290+
+
291+
[source,terminal]
292+
----
293+
$ rosa version
294+
----
295+
------

0 commit comments

Comments
 (0)