Skip to content

Commit

Permalink
feat: improve experience of docs
Browse files Browse the repository at this point in the history
  • Loading branch information
Ph0enixKM committed Jun 16, 2024
1 parent 50f9c14 commit 869b070
Show file tree
Hide file tree
Showing 8 changed files with 199 additions and 120 deletions.
40 changes: 3 additions & 37 deletions docs/by_example/examples.md
Original file line number Diff line number Diff line change
@@ -1,39 +1,5 @@
# Examples
# Example Scripts

Here is an example script to periodically install software updates on an Ubuntu system. The update commands are wrapped in a `main` block, so that all commands between `$` signs can pass up errors with the `?` operator. The script will stop in that case and not execute any further commands.
> WARNING: Experimental standard library is used here. The full documentation covering it will be created soon as it get's more stable.
```ab
import { exit } from "std"
main {
// Print output and log it at the same time.
$ exec > >(tee -a /var/log/autoapt.log) 2>&1 $?
// Log the current date so that we can check when any failed runs happened.
$ date $?
// Internet is slow on Austrian trains. Check the Wifi SSID and stop in that
// case.
silent unsafe $ iwgetid -r | grep -E '(OEBB|WESTlan)' $
if status == 0 {
echo "Skipping updates because of slow Wifi"
exit(0)
}
$ export DEBIAN_FRONTEND=noninteractive $?
$ apt update $?
// By default answer all user interaction questions with yes, for example
// for debconf.
// Use the old configuration file when new config files arrive.
// Also say yes to setting up config files.
$ yes '' | apt \
-o Dpkg::Options::=--force-confold \
-o Dpkg::Options::=--force-confdef \
-y --allow-downgrades --allow-remove-essential \
--allow-change-held-packages \
upgrade $?
// Clean up any packages that are not needed anymore.
$ apt autoremove -y $?
// Also update Snap packages.
$ snap refresh --color=never --unicode=never $?
}
```
Here, you’ll find a collection of practical scripts designed to help you quickly grasp the fundamentals and advanced features of the Amber programming language. Whether you are new to programming or an experienced developer, these examples will guide you through.
39 changes: 39 additions & 0 deletions docs/by_example/ubuntu_updater.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
# Ubuntu Updater

Here is an example script to periodically install software updates on an Ubuntu system. The update commands are wrapped in a `main` block, so that all commands between `$` signs can pass up errors with the `?` operator. The script will stop in that case and not execute any further commands.

```ab
import { exit } from "std"
main {
// Print output and log it at the same time.
$ exec > >(tee -a /var/log/autoapt.log) 2>&1 $?
// Log the current date so that we can check when any failed runs happened.
$ date $?
// Internet is slow on Austrian trains. Check the Wifi SSID and stop in that
// case.
silent unsafe $ iwgetid -r | grep -E '(OEBB|WESTlan)' $
if status == 0 {
echo "Skipping updates because of slow Wifi"
exit(0)
}
$ export DEBIAN_FRONTEND=noninteractive $?
$ apt update $?
// By default answer all user interaction questions with yes, for example
// for debconf.
// Use the old configuration file when new config files arrive.
// Also say yes to setting up config files.
$ yes '' | apt \
-o Dpkg::Options::=--force-confold \
-o Dpkg::Options::=--force-confdef \
-y --allow-downgrades --allow-remove-essential \
--allow-change-held-packages \
upgrade $?
// Clean up any packages that are not needed anymore.
$ apt autoremove -y $?
// Also update Snap packages.
$ snap refresh --color=never --unicode=never $?
}
```
158 changes: 82 additions & 76 deletions docs/index.json
Original file line number Diff line number Diff line change
@@ -1,86 +1,92 @@
{
"docs": [
{
"path": "getting_started/getting_started",
"title": "Getting Started",
"docs": [
"docs": [
{
"path": "getting_started/installation",
"title": "Installation"
"path": "getting_started/getting_started",
"title": "Getting Started",
"docs": [
{
"path": "getting_started/installation",
"title": "Installation"
},
{
"path": "getting_started/usage",
"title": "Usage"
}
]
},
{
"path": "getting_started/usage",
"title": "Usage"
}
]
},
{
"path": "basic_syntax/basic_syntax",
"title": "Basic Syntax",
"docs": [
{
"path": "basic_syntax/data_types",
"title": "Data Types"
},
{
"path": "basic_syntax/expressions",
"title": "Expressions"
},
{
"path": "basic_syntax/variables",
"title": "Variables"
},
{
"path": "basic_syntax/conditions",
"title": "Conditions"
},
{
"path": "basic_syntax/commands",
"title": "Commands"
},
{
"path": "basic_syntax/arrays",
"title": "Arrays"
},
{
"path": "basic_syntax/loops",
"title": "Loops"
},
{
"path": "basic_syntax/functions",
"title": "Functions"
},
{
"path": "basic_syntax/importing",
"title": "Importing"
}
]
},
{
"path": "advanced_syntax/advanced_syntax",
"title": "Advanced Syntax",
"docs": [
{
"path": "advanced_syntax/as_cast",
"title": "As Cast"
},
{
"path": "advanced_syntax/nameof",
"title": "Nameof"
"path": "basic_syntax/basic_syntax",
"title": "Basic Syntax",
"docs": [
{
"path": "basic_syntax/data_types",
"title": "Data Types"
},
{
"path": "basic_syntax/expressions",
"title": "Expressions"
},
{
"path": "basic_syntax/variables",
"title": "Variables"
},
{
"path": "basic_syntax/conditions",
"title": "Conditions"
},
{
"path": "basic_syntax/commands",
"title": "Commands"
},
{
"path": "basic_syntax/arrays",
"title": "Arrays"
},
{
"path": "basic_syntax/loops",
"title": "Loops"
},
{
"path": "basic_syntax/functions",
"title": "Functions"
},
{
"path": "basic_syntax/importing",
"title": "Importing"
}
]
},
{
"path": "advanced_syntax/type_condition",
"title": "Type Condition"
"path": "advanced_syntax/advanced_syntax",
"title": "Advanced Syntax",
"docs": [
{
"path": "advanced_syntax/as_cast",
"title": "As Cast"
},
{
"path": "advanced_syntax/nameof",
"title": "Nameof"
},
{
"path": "advanced_syntax/type_condition",
"title": "Type Condition"
},
{
"path": "advanced_syntax/compiler_flags",
"title": "Compiler Flags"
}
]
},
{
"path": "advanced_syntax/compiler_flags",
"title": "Compiler Flags"
"path": "by_example/examples",
"title": "Amber by Example",
"docs": [
{
"path": "by_example/ubuntu_updater",
"title": "Ubuntu Updater"
}
]
}
]
},
{
"path": "by_example/examples",
"title": "Examples"
}
]
]
}
11 changes: 11 additions & 0 deletions public/internal/warning.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
44 changes: 41 additions & 3 deletions src/components/Markdown/Markdown.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,44 @@ html[mode="light"] .markdown .light-dark img:last-child {
color: var(--text);
}

.markdown .quote {
border-radius: 10px;
padding: 1rem;
border-left: 5px solid var(--border);
background: linear-gradient(
90deg,
color-mix(in srgb, var(--border), transparent 70%),
color-mix(in srgb, var(--border), transparent 90%)
);
}

.markdown .warning {
border-radius: 10px;
padding: 1rem;
border-left: 5px solid #ffa300;
background: linear-gradient(
90deg,
color-mix(in srgb, #ffa300, transparent 70%),
color-mix(in srgb, #ffa300, transparent 90%)
);
}

.quote p, .warning p {
display: inline;
}

.markdown .warning .warning-icon {
width: 1.5rem;
height: 1.5rem;
border-radius: 0;
border: none;
display: inline;
margin: 0;
margin-right: 0.5rem;
padding: 0;
vertical-align: middle;
}

@keyframes fade {
0% {
mask-size: 0rem 0rem;
Expand Down Expand Up @@ -165,15 +203,15 @@ html[mode="light"] .markdown .light-dark img:last-child {
background-color: color-mix(in srgb, var(--code-background), var(--text) 20%);
opacity: 1;
}

.container:hover .side-action:hover {
background-color: color-mix(in srgb, var(--text), transparent 20%);
}
}
}

@media screen and (hover: none) {
.container .side-action {
left: -50px;
background-color: var(--text);
}
}
}
14 changes: 14 additions & 0 deletions src/components/Markdown/Markdown.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,20 @@ class MarkdownRenderer extends Renderer {
return `<code class="${style.inline}">${text}</code>`
}

blockquote(text: string): string {
const warningText = 'WARNING:'
const isWarning = (text.replace('<p>', '').startsWith(warningText));
const className = isWarning ? 'warning' : 'quote'
let result = text;
if (isWarning) {
const img = `<img src="/internal/warning.svg" class="${style["warning-icon"]}" />`
result = img + result.replace(warningText, '')
}
console.log(text.replace('<p>', '').startsWith(''));
if (text)
return `<blockquote class="${style[className]}">${result}</blockquote>`
}

code(rawCode: string, lang: string, escaped: boolean) {
let code = rawCode.trim()
if (this.options.highlight) {
Expand Down
7 changes: 6 additions & 1 deletion src/components/SideBar/SideBar.module.css
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,11 @@
white-space: nowrap;
}

.indent[indent="0"] {
color: var(--text);
font-weight: 500;
}

.indent[relation="child"]:not([indent="0"])::before {
content: "";
display: block;
Expand Down Expand Up @@ -152,4 +157,4 @@

.links a:last-child {
margin-bottom: 0;
}
}
6 changes: 3 additions & 3 deletions src/components/SideBar/SideBar.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ export default function SideBar({ headers, isFixed = false }: Props) {
const onPageRef = React.useRef<HTMLDivElement>(null)
const tocRef = React.useRef<HTMLDivElement>(null)

const getHeaderLink = (header: string) => {
const getHeaderLink = (header: string) => {
return ['#', header.toLowerCase().replace(/[^\w]+/g, '-')].join('')
}

Expand Down Expand Up @@ -117,7 +117,7 @@ export default function SideBar({ headers, isFixed = false }: Props) {
<React.Fragment key={path}>
<Link href={`/${path}`} key={path}>
<Text block>
<div className={style.indent}>{title}</div>
<div className={style.indent} {...{ indent: "0" }}>{title}</div>
</Text>
</Link>
{docs && docs.map(({ path, title }, index) => (
Expand All @@ -143,4 +143,4 @@ export default function SideBar({ headers, isFixed = false }: Props) {
</div>
</div>
)
}
}

0 comments on commit 869b070

Please sign in to comment.