From 869b070a6f040a60759f2a487ce7212cb1723328 Mon Sep 17 00:00:00 2001 From: Phoenix Himself Date: Sun, 16 Jun 2024 21:34:19 +0200 Subject: [PATCH] feat: improve experience of docs --- docs/by_example/examples.md | 40 +---- docs/by_example/ubuntu_updater.md | 39 +++++ docs/index.json | 158 ++++++++++---------- public/internal/warning.svg | 11 ++ src/components/Markdown/Markdown.module.css | 44 +++++- src/components/Markdown/Markdown.tsx | 14 ++ src/components/SideBar/SideBar.module.css | 7 +- src/components/SideBar/SideBar.tsx | 6 +- 8 files changed, 199 insertions(+), 120 deletions(-) create mode 100644 docs/by_example/ubuntu_updater.md create mode 100644 public/internal/warning.svg diff --git a/docs/by_example/examples.md b/docs/by_example/examples.md index 89287d9..62a560b 100644 --- a/docs/by_example/examples.md +++ b/docs/by_example/examples.md @@ -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. diff --git a/docs/by_example/ubuntu_updater.md b/docs/by_example/ubuntu_updater.md new file mode 100644 index 0000000..b16594d --- /dev/null +++ b/docs/by_example/ubuntu_updater.md @@ -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 $? +} +``` diff --git a/docs/index.json b/docs/index.json index 25aa2a1..f153963 100644 --- a/docs/index.json +++ b/docs/index.json @@ -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" - } - ] + ] } diff --git a/public/internal/warning.svg b/public/internal/warning.svg new file mode 100644 index 0000000..5e2be2d --- /dev/null +++ b/public/internal/warning.svg @@ -0,0 +1,11 @@ + + + 256x256@1x + + + + + + + + \ No newline at end of file diff --git a/src/components/Markdown/Markdown.module.css b/src/components/Markdown/Markdown.module.css index 36b7a30..8214f2f 100644 --- a/src/components/Markdown/Markdown.module.css +++ b/src/components/Markdown/Markdown.module.css @@ -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; @@ -165,10 +203,10 @@ 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) { @@ -176,4 +214,4 @@ html[mode="light"] .markdown .light-dark img:last-child { left: -50px; background-color: var(--text); } -} \ No newline at end of file +} diff --git a/src/components/Markdown/Markdown.tsx b/src/components/Markdown/Markdown.tsx index b9f455a..5db8b6a 100644 --- a/src/components/Markdown/Markdown.tsx +++ b/src/components/Markdown/Markdown.tsx @@ -35,6 +35,20 @@ class MarkdownRenderer extends Renderer { return `${text}` } + blockquote(text: string): string { + const warningText = 'WARNING:' + const isWarning = (text.replace('

', '').startsWith(warningText)); + const className = isWarning ? 'warning' : 'quote' + let result = text; + if (isWarning) { + const img = `` + result = img + result.replace(warningText, '') + } + console.log(text.replace('

', '').startsWith('')); + if (text) + return `

${result}
` + } + code(rawCode: string, lang: string, escaped: boolean) { let code = rawCode.trim() if (this.options.highlight) { diff --git a/src/components/SideBar/SideBar.module.css b/src/components/SideBar/SideBar.module.css index 07a6be1..c66ad6f 100644 --- a/src/components/SideBar/SideBar.module.css +++ b/src/components/SideBar/SideBar.module.css @@ -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; @@ -152,4 +157,4 @@ .links a:last-child { margin-bottom: 0; -} \ No newline at end of file +} diff --git a/src/components/SideBar/SideBar.tsx b/src/components/SideBar/SideBar.tsx index a5da566..aa6edf7 100644 --- a/src/components/SideBar/SideBar.tsx +++ b/src/components/SideBar/SideBar.tsx @@ -64,7 +64,7 @@ export default function SideBar({ headers, isFixed = false }: Props) { const onPageRef = React.useRef(null) const tocRef = React.useRef(null) - const getHeaderLink = (header: string) => { + const getHeaderLink = (header: string) => { return ['#', header.toLowerCase().replace(/[^\w]+/g, '-')].join('') } @@ -117,7 +117,7 @@ export default function SideBar({ headers, isFixed = false }: Props) { -
{title}
+
{title}
 {docs && docs.map(({ path, title }, index) => ( @@ -143,4 +143,4 @@ export default function SideBar({ headers, isFixed = false }: Props) { ) -} \ No newline at end of file +}