Enhance documentation (#494)

.github/workflows/docs.yml

@@ -25,7 +25,9 @@ jobs:
           python-version: 3.x
 
       - name: Install dependencies
-        run: pip install -r docs/requirements.txt
+        run: |
+          sudo apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev pngquant
+          pip install -r docs/requirements.txt
 
       - name: Build and deploy
         working-directory: docs

docs/docs/intro.md

@@ -5,4 +5,4 @@ title: Introduction
 Spice is a compiled language which sets a focus on performance and practicality. It is considered as a systems language,
 which means that is rather not suitable for coding user interfaces, but for coding drivers and cli tools. Spice has
 support for cross-compiling for multiple target platforms. In order to get started, visit the
-[installation guide](../install/linux).
+[installation guide](install/linux.md).

docs/docs/language/arrays.md

@@ -2,7 +2,7 @@
 title: Arrays
 ---
 
-You can use arrays in Spice for any [primitive](../primitive-types) or custom [struct](../structs) data type.
+You can use arrays in Spice for any [primitive](primitive-types.md) or custom [struct](structs.md) data type.
 
 ## Usage
 

docs/docs/language/builtin-types.md

@@ -2,10 +2,10 @@
 title: Builtin data types
 ---
 
-In extension to the [primitive data types](../primitive-types), Spice offers builtin data types.
+In extension to the [primitive data types](../primitive-types.md), Spice offers builtin data types.
 
 ## The `String` data type
-In opposite to the [string primitive type](../primitive-types#the-string-data-type), the `String` builtin type is
+In opposite to the [string primitive type](primitive-types.md#the-string-data-type), the `String` builtin type is
 mutable and offers several ways to modify the contained value.
 
 !!! tip "Tip"

docs/docs/language/casts.md

@@ -2,7 +2,7 @@
 title: Type Casts
 ---
 
-Sometimes it is useful to directly cast [a type](../primitive-types) to another one. Spice offers type casting for some
+Sometimes it is useful to directly cast [a type](primitive-types.md) to another one. Spice offers type casting for some
 type combinations. Additionally, the casting operator can always be applied when the source type matches the cast
 destination type.
 

docs/docs/language/constructors-destructors.md

@@ -42,7 +42,7 @@ f<int> main() {
 }
 ```
 
-The `ctor` method can also be called manually like calling [other methods](./methods).
+The `ctor` method can also be called manually like calling [other methods](methods.md).
 
 ## Destructors
 You have the option to create a destructor by providing a `dtor` method on a struct. It does not allow any arguments and has no

docs/docs/language/do-while-loops.md

@@ -4,8 +4,8 @@ title: Do-While Loops
 
 Do-While loops are designed to do something until a certain condition evaluates to `false`, but at least execute the action once.
 This means, that a do-while loop could also run infinitely when the condition never gets fulfilled. <br>
-Like the [if statement](../if-statements), the condition of the `do-while` loop must evaluate to a
-[boolean value](../primitive-types#the-bool-data-type), but can hold complex, nested expressions.
+Like the [if statement](if-statements.md), the condition of the `do-while` loop must evaluate to a
+[boolean value](primitive-types.md#the-bool-data-type), but can hold complex, nested expressions.
 
 ## Usage
 
@@ -29,5 +29,5 @@ do {
 ```
 
 !!! tip "Usage of loop alternatives"
-    If you somehow know how many times you want to execute something, we recommend you to use a [for loop](../for-loops)
-    instead. If you want to iterate over a container of items, consider using the [foreach loop](../foreach-loops).
+    If you somehow know how many times you want to execute something, we recommend you to use a [for loop](for-loops.md)
+    instead. If you want to iterate over a container of items, consider using the [foreach loop](foreach-loops.md).

docs/docs/language/for-loops.md

@@ -19,5 +19,5 @@ for int i = 1; i <= 10; i++ {
 
 !!! tip "Usage of loop alternatives"
     For loops should only be used when it is foreseeable how often a block of code will run. If this is not the case, it
-    is recommended to use the [while loop](../while-loops) or [do-while loop](../do-while-loops) instead. If you want to
-    iterate over a container of items, consider using the [foreach loop](../foreach-loop).
+    is recommended to use the [while loop](while-loops.md) or [do-while loop](do-while-loops.md) instead. If you want to
+    iterate over a container of items, consider using the [foreach loop](foreach-loops.md).

docs/docs/language/foreach-loops.md

@@ -3,7 +3,7 @@ title: Foreach Loops
 ---
 
 Foreach loops can be used to iterate over containers, that offer iterator implementations like `Vector`, `ArrayList`,
-etc. as well as [arrays](../arrays) of arbitrary elements and number ranges.
+etc. as well as [arrays](arrays.md) of arbitrary elements and number ranges.
 
 ## Usage
 
@@ -38,5 +38,5 @@ foreach long idx, string word : welcomeMessage {
 
 !!! tip "Usage of loop alternatives"
     Foreach loops should only be used when you have a container data structure and want to iterate over its items.
-    If this is not the case, we recommend using the [for loop](../for-loops), [while loop](../while-loops) or
-	[do-while loop](../do-while-loops) instead.
+    If this is not the case, we recommend using the [for loop](for-loops.md), [while loop](while-loops.md) or
+	[do-while loop](do-while-loops.md) instead.

docs/docs/language/functions.md

@@ -37,4 +37,4 @@ int result1 = demoFunction("another input", 1.0);
 
 !!! tip
     If you only want to execute some actions and don't need to return a value to the caller, please consider to use
-    [procedures](../procedures) instead of functions.
+    [procedures](procedures.md) instead of functions.

docs/docs/language/generics.md

@@ -2,8 +2,8 @@
 title: Generics
 ---
 
-Spice offers basic support for generics. [Structs](./structs) and [Interfaces](./interfaces) as well as [functions](./functions)
-and [procedures](./procedures) can be marked as generic by attaching a template list with one or more generic types to it.
+Spice offers basic support for generics. [Structs](structs.md) and [Interfaces](interfaces.md) as well as [functions](functions.md)
+and [procedures](procedures.md) can be marked as generic by attaching a template list with one or more generic types to it.
 
 Spice resolves the substantiations of generic types at compile time. This helps to keep the runtime performance up.
 Generic function substantiations that are unused, are removed by the compiler automatically.
@@ -52,5 +52,5 @@ p Vector.print() {
 ```
 
 The above example shows, that you can use the generic type as part of struct field types. Like normal structs, generic structs can
-also have [methods](./methods). The concrete types for the generic types, used for the parent struct, are inherited by the method,
+also have [methods](./methods.md). The concrete types for the generic types, used for the parent struct, are inherited by the method,
 so you do not have to define the method above with following signature: `Vector<T>.print()`.

docs/docs/language/hello-world.md

@@ -6,7 +6,7 @@ title: Hello World
 
 In this example, we will code a simple "Hello World" program in Spice. What it does is to simply print "Hello World!" to the
 console when it gets started. The guide assumes, that you already have Spice
-[installed on your development system](https://www.spicelang.com/install/linux) and are ready to go.
+[installed on your development system](../install/linux.md) and are ready to go.
 
 ## Write your first program
 

docs/docs/language/if-statements.md

@@ -3,7 +3,8 @@ title: If Statements
 ---
 
 If statements can be used to execute parts of the program only if a condition is `true`. The specialist term for this is "branching". <br>
-The condition of `if` statements can consist of more complex expressions, but always have to evaluate to a [bool data type](../primitive-types#the-bool-data-type).
+The condition of `if` statements can consist of more complex expressions, but always have to evaluate to a
+[bool data type](primitive-types.md#the-bool-data-type).
 
 ## Usage
 

docs/docs/language/main-function.md

@@ -16,15 +16,15 @@ f<int> main() {
 }
 ```
 
-Like any other [function](../functions), the `main` function automatically declares the variable `result` of the same type as the
+Like any other [function](functions.md), the `main` function automatically declares the variable `result` of the same type as the
 function return type. You then have the option to use either the return statement (e.g.: `return 1;`) or assign a value to the
 `result` variable. If you choose the second option, the value of this variable gets returned at the end of the function body.
 Unlike normal functions, the `main` function has `0` as the initial value assigned to the `result` variable for reasons of
 convenience and to not always have to write `return 0;` or `result = 0;` to exit the program with a positive exit code.
 
 !!! info "Hello World program"
     Now, as you know how to start a program in Spice, you may like to write your first Spice program. Visit the guide for the
-    [Hello World example](../hello-world) to get started!
+    [Hello World example](hello-world.md) to get started!
 
 ## Command Line Arguments
 Spice programs can accept command line arguments similar you would write it in C:

docs/docs/language/methods.md

@@ -2,7 +2,7 @@
 title: Methods
 ---
 
-Methods in Spice basically are [functions](../functions) / [procedures](../procedures), assigned to a struct. Within methods,
+Methods in Spice basically are [functions](functions.md) / [procedures](procedures.md), assigned to a struct. Within methods,
 fields of the parent struct can be accessed like this: `this.fieldName`.
 
 ## Usage
@@ -34,5 +34,5 @@ Content: Hello World!
 ```
 
 !!! tip
-    You can initialize or destroy structs by using [constructors](../constructors) and [destructors](,./destructors). Read more
-    about those in the respective documentation section.
+    You can initialize or destroy structs by using [constructors and destructors](constructors-destructors.md).
+    Read more about those in the respective documentation section.

docs/docs/language/operator-overloading.md

@@ -2,7 +2,7 @@
 title: Operator Overloading
 ---
 
-Spice allows overloading operators for [custom struct types](../structs).
+Spice allows overloading operators for [custom struct types](structs.md).
 Currently, this works for the operators `+`, `-`, `*`, `/`, `==`, `!=`, `<<`, `>>`, `+=`, `-=`, `*=`, `/=`,
 `++` (postfix) and `--` (postfix).
 In the future, more operators will be supported for overloading.

docs/docs/language/primitive-types.md

@@ -2,7 +2,8 @@
 title: Primitive data types
 ---
 
-Spice supports eight different primitive data types out of the box: `double`, `int`, `short`, `long`, `byte`, `char`, `string` and `bool`. In addition, there is a builtin type-inferred type, called `dyn`.
+Spice supports eight different primitive data types out of the box: `double`, `int`, `short`, `long`, `byte`, `char`, `string` and
+`bool`. In addition, there is a builtin type-inferred type, called `dyn`.
 Let us take a look at each one individually!
 
 ## The `double` data type
@@ -84,7 +85,7 @@ variable2 = "Hello World!";
 
 !!! info "Note"
     This type of string is immutable. So if you want to mutate your string at runtime, you can use the
-    [builtin String data type](../builtin-types#the-string-data-type).
+    [builtin String data type](builtin-types.md#the-string-data-type).
 
 !!! tip "Tip"
     Use the `string` primitive type over the `String` builtin type as much as possible, due to its advantages in runtime
@@ -103,11 +104,15 @@ variable2 = false;
 ```
 
 !!! info "Additional information"
-    Many language components like [if statements](../if-statements), [for loops](../for-loops), [while loops](../while-loops), etc. use the `bool` data type as evaluation unit for conditions.
+    Many language components like [if statements](if-statements.md), [for loops](for-loops.md),
+    [while loops](while-loops.md), etc. use the `bool` data type as evaluation unit for conditions.
 	You can find more information about that in the respective sections.
 
 ## The `dyn` data type
-The `dyn` data type is a more unconventional data type. Dyn stands for dynamic and means that the `dyn` data type can hold any value of one of the eight types `double`, `int`, `short`, `long`, `byte`, `char`, `string` or `bool`. The concrete type of a `dyn` variable gets inferred at compile time so that the language stays type-safe. This also means, that as soon as you assign a value to a `dyn` variable, the type gets set fixed and is not mutable anymore.
+The `dyn` data type is a more unconventional data type. Dyn stands for dynamic and means that the `dyn` data type can hold any
+value of one of the eight types `double`, `int`, `short`, `long`, `byte`, `char`, `string` or `bool`. The concrete type of a `dyn`
+variable gets inferred at compile time so that the language stays type-safe. This also means, that as soon as you assign a value
+to a `dyn` variable, the type gets set fixed and is not mutable anymore.
 
 Dyn variables can be defined like this:
 
@@ -121,4 +126,5 @@ variable3 = "demo string";
 ```
 
 !!! note "Usage of the dyn data type"
-    The dyn data type can not be used everywhere. Function arguments can only be declared as `dyn`, when they have a default value attached to them. For more information about [functions](../functions), visit the respective documentation section.
+    The dyn data type can not be used everywhere. Function arguments can only be declared as `dyn`, when they have a default value
+    attached to them. For more information about [functions](functions.md), visit the respective documentation section.

docs/docs/language/procedures.md

@@ -38,5 +38,5 @@ demoProcedure(7, true);
 ```
 
 !!! tip
-    If you want to calculate something and need to return a value to the caller, please consider to use [functions](../functions)
-    instead of procedures.
+    If you want to calculate something and need to return a value to the caller, please consider to use
+    [functions](functions.md) instead of procedures.

docs/docs/language/references.md

@@ -1,7 +1,7 @@
 ---
 title: References
 ---
-In addition to [pointers](../pointers), Spice supports references. Under the hood, this works with non-nullable pointers.
+In addition to [pointers](pointers.md), Spice supports references. Under the hood, this works with non-nullable pointers.
 
 ## Usage - local variables
 

docs/docs/language/structs.md

@@ -16,7 +16,7 @@ type Person struct {
 }
 ```
 
-Structs can only be declared in the global scope, like [functions](../functions) and [procedures](../procedures).
+Structs can only be declared in the global scope, like [functions](functions.md) and [procedures](procedures.md).
 
 For creating an instance of the declared struct, you can pass values for either all or none of the fields in curly braces.
 To access a field of the instance, you can address the field by its name:

docs/docs/language/while-loops.md

@@ -4,8 +4,8 @@ title: While Loops
 
 While loops are designed to do something until a certain condition evaluates to `false`.
 This means, that a while loop could also run infinitely when the condition never gets fulfilled. <br>
-Like the [if statement](../if-statements), the condition of the `while` loop must evaluate to a
-[boolean value](../primitive-types#the-bool-data-type), but can hold complex, nested expressions.
+Like the [if statement](if-statements.md), the condition of the `while` loop must evaluate to a
+[boolean value](primitive-types.md#the-bool-data-type), but can hold complex, nested expressions.
 
 ## Usage
 
@@ -29,6 +29,5 @@ while true {
 ```
 
 !!! tip "Usage of loop alternatives"
-    If you somehow know how many times you want to execute something, we recommend you to use a [for loop](../for-loops)
-    instead. If you want to iterate over a container of items, consider using the [foreach loop](../foreach-loops).
-
+    If you somehow know how many times you want to execute something, we recommend you to use a [for loop](for-loops.md)
+    instead. If you want to iterate over a container of items, consider using the [foreach loop](foreach-loops.md).

docs/mkdocs.yml

@@ -11,15 +11,17 @@ theme:
   name: material
   custom_dir: docs/overrides
   language: en
-  logo: static/avatar.png
   favicon: static/favicon-96x96.ico
+  logo: static/avatar.png
   include_search_page: false
   search_index_only: true
   features:
     - navigation.instant
     - navigation.tabs
+    - navigation.top
     - content.code.copy
     - content.action.edit
+    - content.action.view
     - announce.dismiss
   palette:
     - media: "(prefers-color-scheme)"  # System preference
@@ -52,8 +54,12 @@ plugins:
       - en
   - minify:
       minify_html: true
+  - social
 
 extra:
+  status:
+    new: Recently added
+    deprecated: Deprecated
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/spicelang/spice
@@ -115,7 +121,6 @@ nav:
   - contributing.md
 
 markdown_extensions:
-  - codehilite
   - meta
   - footnotes
   - admonition
@@ -126,6 +131,13 @@ markdown_extensions:
       alternate_style: true
   - pymdownx.superfences
   - attr_list
+  - pymdownx.highlight:
+      auto_title: true
+      linenums: true
+      anchor_linenums: true
+      use_pygments: true
+  - pymdownx.inlinehilite
+  - pymdownx.superfences
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg

docs/requirements.txt

@@ -1,4 +1,5 @@
 mkdocs-material==9.5.12
+mkdocs-material[imaging]==9.5.12
 mkdocs-minify-plugin==0.8.0
 mkdocs-git-revision-date-localized-plugin==1.2.4
 mkdocs-git-committers-plugin-2==2.3.0