mirror of
https://github.com/clearml/clearml-docs
synced 2025-02-25 13:45:33 +00:00
Add Report Markdown Guide (#421)
This commit is contained in:
parent
928190e0dd
commit
f5cf2bb98a
BIN
docs/img/reports_blockquotes.png
Normal file
BIN
docs/img/reports_blockquotes.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 5.4 KiB |
BIN
docs/img/reports_headings.png
Normal file
BIN
docs/img/reports_headings.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 3.1 KiB |
BIN
docs/img/reports_horizontal_rules.png
Normal file
BIN
docs/img/reports_horizontal_rules.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 567 B |
BIN
docs/img/reports_ordered_list.png
Normal file
BIN
docs/img/reports_ordered_list.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 2.8 KiB |
BIN
docs/img/reports_table.png
Normal file
BIN
docs/img/reports_table.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 11 KiB |
BIN
docs/img/reports_unordered_list.png
Normal file
BIN
docs/img/reports_unordered_list.png
Normal file
Binary file not shown.
After ![]() (image error) Size: 6.8 KiB |
@ -93,6 +93,205 @@ of a report card to open its context menu and access report actions:
|
||||
### Create New Reports
|
||||
|
||||
To create a new project, click the **+ NEW REPORT** button in the top right of the page,
|
||||
which will open a **New Report** modal.
|
||||
which will open a **New Report** modal.
|
||||
|
||||

|
||||
|
||||
## MarkDown Formatting Quick Guide
|
||||
|
||||
The following is a quick reference for the MarkDown syntax that can be used in ClearML Reports.
|
||||
|
||||
### Heading Levels
|
||||
|
||||
To create headings, add `#` in front of the phrases that you want to turn into
|
||||
headings. The number of `#` signs correspond to the heading level (i.e. `#` for level-1 heading, `##` for level-2, etc.):
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code># H1<br/>## H2<br/>### H3<br/>#### H4<br/>##### H5<br/>###### H6</code>||
|
||||
|
||||
### Text Emphasis
|
||||
|
||||
The following table presents the text format options:
|
||||
|
||||
|Format Option| MarkDown | Rendered Output |
|
||||
|---|---|---|
|
||||
|Bold | \*\*This is bold text\*\* and \_\_so is this\_\_ |**This is bold text** and __so is this__|
|
||||
|Italics | \*This is italic text\* and \_so is this\_|*This is italic text* and _so is this_|
|
||||
|Strikethrough |\~\~Strikethrough\~\~ |~~Strikethrough~~|
|
||||
|Inline Code | \`this is code\`| `this is code` |
|
||||
|
||||
### Blockquotes
|
||||
|
||||
To create a blockquote, add a `>` before each line of the quote. Nest blockquotes by adding additional
|
||||
`>` signs before each line of the nested blockquote.
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code>\> Blockquote<br/>\>\> Nested quote 1<br/>\>\>\> Nested quote 2</code>||
|
||||
|
||||
### Lists
|
||||
|
||||
#### Ordered List
|
||||
|
||||
Create an ordered list by numbering the list items with numbers followed by periods. The list items do not have to be numbered
|
||||
correctly, but the list will be rendered numerically starting with `1.`.
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code>1. Item 1<br/>2. Item 2<br/>1. Item 3<br/>1. Item 4</code>||
|
||||
|
||||
#### Unordered List
|
||||
|
||||
Create an unordered list by starting each line with the `+`, `-`, or `*` signs. Different
|
||||
signs can be used to create the bullets in the same list, but they are all rendered uniformly.
|
||||
|
||||
You can also use checkmarks (`* [x]`), following any of the bullet signs.
|
||||
|
||||
To nest lists, indent nested items 2 spaces more than their parent list item.
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code>+ Item 1<br/>+ Item 2<br/> - Sub-item a:<br/> \* Sub-sub-item x<br/> + Sub-sub-item y<br/> - Sub-sub-item z<br/>\* [x] A checkmark </code>||
|
||||
|
||||
|
||||
### Tables
|
||||
|
||||
MarkDown code for a table looks like this:
|
||||
|
||||
```markdown
|
||||
| | Align Right | Align Left | Align Center |
|
||||
| -------- | -----------:|:---------- |:------------:|
|
||||
| 1 | 1 | 1 | 1 |
|
||||
| 11 | 11 | 11 | 11 |
|
||||
```
|
||||
|
||||
The rendered output should look like this:
|
||||
|
||||

|
||||
|
||||
Add the table column names in the first row; each name is preceded and followed by a pipe (`|`).
|
||||
In the second row, add sets of at least three hyphens (`---`) for each column, and add a pipe before and after each set
|
||||
of hyphens. In the second row, you can specify each table column's contents alignment. To align the contents to the
|
||||
left, place a colon (`:`) to the left of the hyphens. To align right, place a colon to the right of the hyphens. To
|
||||
center align, place colons on both sides of the hyphens.
|
||||
|
||||
### Code
|
||||
|
||||
To render inline code, surround the code with single backticks (<code>\`</code>). For example \`code\` will be rendered `code`.
|
||||
|
||||
To create block code, use one of the following options:
|
||||
* Indent the code
|
||||
```
|
||||
from clearml import Task
|
||||
|
||||
t = Task.init(project_name='My project', task_name='Base')
|
||||
```
|
||||
|
||||
* Surround code with "fences"--three backticks (<code>```</code>):
|
||||
|
||||
```
|
||||
from clearml import Task
|
||||
|
||||
t = Task.init(project_name='My project', task_name='Base')
|
||||
```
|
||||
|
||||
Both of these options will be rendered as:
|
||||
|
||||
```
|
||||
from clearml import Task
|
||||
|
||||
t = Task.init(project_name='My project', task_name='Base')
|
||||
```
|
||||
|
||||
#### Syntax Highlighting
|
||||
|
||||
To display syntax highlighting, specify the coding language after the first fence (e.g. <code>\```python</code>, <code>\```json</code>, <code>\```js</code>, etc.):
|
||||
|
||||
```python
|
||||
from clearml import Task
|
||||
|
||||
t = Task.init(project_name='My project', task_name='Base')
|
||||
```
|
||||
|
||||
The rendered output should look like this:
|
||||
|
||||
```py
|
||||
from clearml import Task
|
||||
|
||||
t = Task.init(project_name='My project', task_name='Base')
|
||||
```
|
||||
|
||||
|
||||
### Links
|
||||
|
||||
To create a link, enclose link text inside brackets, followed by the URL link enclosed in parentheses:
|
||||
|
||||
```
|
||||
[link text](https://clear.ml)
|
||||
```
|
||||
|
||||
The rendered output should look like this:
|
||||
[link text](https://clear.ml)
|
||||
|
||||
To add a title to the link, which you can see in a tooltip when hovering over the link, add the title after the URL
|
||||
link in the parentheses:
|
||||
|
||||
```
|
||||
[link with title](https://clear.ml "ClearML Documentation")
|
||||
```
|
||||
|
||||
The rendered output should look like this: [link with title](https://clear.ml "ClearML Documentation"). Hover over the
|
||||
link to see the link's title.
|
||||
|
||||
### Collapsible Sections
|
||||
|
||||
The MarkDown code for a collapsible panel looks like this:
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code><details\><br/> <summary\>Section title</summary\><br/> Collapsible Section Contents<br/></details\></code>|<details><summary>Section title</summary>Collapsible Section Contents</details>|
|
||||
|
||||
The collapsible panel is surrounded by `<details>` tags. Within the `<details>` tag, add the section's title between
|
||||
the `<summary>` tags. This title can be seen when the panel is collapsed. After the `</summary>` tag, add the panel
|
||||
contents.
|
||||
|
||||
### Horizontal Rules
|
||||
|
||||
Create horizontal lines using three hyphens (`---`), underscores (`___`), or asterisks (`***`):
|
||||
|
||||
| MarkDown | Rendered Output |
|
||||
|---|---|
|
||||
| <code>---<br/><br/>___<br/><br/>***</code>||
|
||||
|
||||
|
||||
### Images
|
||||
|
||||
To add an image, add an exclamation point, followed by the alt text enclosed by brackets, followed by the link to the
|
||||
image enclosed in parentheses:
|
||||
|
||||
```
|
||||

|
||||
```
|
||||
|
||||
The rendered output should look like this:
|
||||
|
||||

|
||||
|
||||
To add a title to the image, which you can see in a tooltip when hovering over the image, add the title after the image's
|
||||
link:
|
||||
|
||||
```
|
||||

|
||||
```
|
||||
The rendered output should look like this:
|
||||
|
||||

|
||||
|
||||
Hover over the image to see its title.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||

|
Loading…
Reference in New Issue
Block a user