Merge pull request #48 from yassinebenaid/dev

yassinebenaid · web-flow · commit 5c6d637f4e15 · 2024-12-12T19:22:34.000+01:00
Improve documentation
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
     <img width="200" src="./docs/public/logo.png"/>
 
 # Bunster
-    
+
 </div>
 
 <div align="center">
@@ -15,32 +15,32 @@
 
 Have you ever wished your shell scripts could be faster, more portable, and secure ? **Bunster** brings this to life by transforming your shell scripts into efficient, standalone binaries that are easy to distribute and deploy across platforms _(only unix is supported at the moment)_.
 
-Unlike other tools, **Bunster** doesn’t just wrap your scripts in a binary—it compiles them down to efficient native machine code, leveraging the powerful Go toolchain. This ensures performance, portability, and robustness, making **Bunster** a unique solution for modern developers.
+Unlike other tools, **Bunster** doesn’t just wrap your scripts in a binary—it compiles them down to efficient native machine code, leveraging the powerful Go toolchain. This ensures performance, portability, and robustness.
 
 Technically speaking, **Bunster** is not a complete compiler, But rather a **Transplier** that generates **GO** code out of your scripts. Then, opionally uses the **Go Toolchain** to compile the code to an executable program.
 
-**Bunster** targets `bash` scripts in particular. The current syntax and features are all inherited from `bash`. other shells support will be added soon.  
+**Bunster** targets `bash` scripts in particular. The current syntax and features are all inherited from `bash`. other shells support will be added soon.
 
 ### Motivation
 - **Different Shells support**: Bunster currently aims to be compatible `Bash` as a starting move. then other popular shells in future.
 - **Security**: as you may guess, humans cannot read machine code, so why not to compile your scripts to such format.
 - **Modules**: something shell scripts lack is a module system, people want to share their code to be used by others, but the infrastructure doesn't allow them. Well, **Bunster** introduces a module system that allow you to publish your scripts as a modules consumed by other users.
-- **Performance**: the shell (including bash, zsh ...etc) rely on forking to run your scripts, this means, if you have a script of 3 commands, the shell will have to fork it self 3 times to run each command. This allows the shell to play with file descriptors and other resouces freely. But adds a lot of performance overhead. **Bunster** runs your entire scripts in a single process. and uses [goroutines](https://go.dev/tour/concurrency/1) for background commands. **Bunster** even has its own file descripor system managed by it's runtime. this means less syscalls, thus, better performance. 
+- **Performance**: the shell (including bash, zsh ...etc) rely on forking to run your scripts, this means, if you have a script of 3 commands, the shell will have to fork it self 3 times to run each command. This allows the shell to play with file descriptors and other resouces freely. But adds a lot of performance overhead. **Bunster** runs your entire scripts in a single process. and uses [goroutines](https://go.dev/tour/concurrency/1) for background commands. **Bunster** even has its own file descripor system managed by it's runtime. this means less syscalls, thus, better performance.
 
-> [!WARNING]  
+> [!WARNING]
 > This project is in its early phase of development and is not yet ready for production. Not all features are implemented yet. But, plenty of them are already working. such as simple command invokation, redirections, environment variables and more.
 
 ### Versionning
-**Bunster** follows [SemVer](https://semver.org/) system for release versionning. On each `v0.x.0` release, You would expect adding support for new features (can be new shell feature, improvement in the build process, some custom features ...etc.) . On each `v0.N.x` release, you would expect bug fixes and documentation enhancments. 
+**Bunster** follows [SemVer](https://semver.org/) system for release versionning. On each `v0.x.0` release, You would expect adding support for new features (can be new shell feature, improvement in the build process, some custom features ...etc.) . On each `v0.N.x` release, you would expect bug fixes and documentation enhancments.
 
-Once we reach the `v1.0.0`, you must expect a +90% of compatibility with `bash`. A module system, a [static assets embedding capabilities](https://pkg.go.dev/embed) and a plenty of other features to make `shell` scripts feel like any other modern programming language.  
+Once we reach the `v1.0.0`, you must expect a +90% of compatibility with `bash`. A module system, a [static assets embedding capabilities](https://pkg.go.dev/embed) and a plenty of other features to make `shell` scripts feel like any other modern programming language.
 
 Adding support for additional shells is not planned until our first stable release `v1`. All regarding contributions will remain open until then.
 
 ### Installation
-Checkout the [documentation](https://bunster.netlify.app) for different ways of installation. 
+Checkout the [documentation](https://bunster.netlify.app) for different ways of installation.
 
-### Contributing 
+### Contributing
 Thank you for considering contributing to the **Bunster** project! The contribution guide can be found in the [documentation](https://bunster.netlify.app).
 
 ### Code Of Conduct
@@ -53,4 +53,3 @@ Plase check out our [Security Policy](https://github.com/yassinebenaid/bunster/t
 
 ### Licence
 The Bunster project is open-sourced software licensed under the [GPL3.0 license](https://www.gnu.org/licenses/gpl-3.0.en.html).
-
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -2,32 +2,36 @@ import { defineConfig } from "vitepress";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
-	title: "Bunster",
-	description:
-		"Compile shell scripts to native self-contained executable programs",
-	themeConfig: {
-		// https://vitepress.dev/reference/default-theme-config
-		nav: [
-			{ text: "Home", link: "/" },
-			{ text: "Examples", link: "/markdown-examples" },
-		],
+  title: "Bunster",
+  description:
+    "Compile shell scripts to native self-contained executable programs",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: "Documentation", link: "/quick-start" },
+      { text: "Installation", link: "/installation" },
+    ],
 
-		sidebar: [
-			{
-				text: "Examples",
-				items: [
-					{ text: "Markdown Examples", link: "/markdown-examples" },
-					{ text: "Runtime API Examples", link: "/api-examples" },
-				],
-			},
-		],
+    sidebar: [
+      {
+        items: [
+          { text: "Quick Start", link: "/quick-start" },
+          { text: "Installation", link: "/installation" },
+        ],
+      },
+    ],
 
-		socialLinks: [
-			{ icon: "github", link: "https://github.com/yassinebenaid/bunster" },
-		],
-	},
-	head: [
-		["link", { rel: "manifest", href: "/site.webmanifest" }],
-		["link", { rel: "icon", type: "image/x-icon", href: "/favicon.ico" }],
-	],
+    socialLinks: [
+      { icon: "github", link: "https://github.com/yassinebenaid/bunster" },
+    ],
+
+    footer: {
+      message: "Released under the GPLv3 License.",
+      copyright: "Copyright © 2024-present Yassine Benaid",
+    },
+  },
+  head: [
+    ["link", { rel: "manifest", href: "/site.webmanifest" }],
+    ["link", { rel: "icon", type: "image/x-icon", href: "/favicon.ico" }],
+  ],
 });
diff --git a/docs/api-examples.md b/docs/api-examples.md
diff --git a/docs/index.md b/docs/index.md
@@ -11,17 +11,17 @@ hero:
     alt: Bunster
   actions:
     - theme: brand
-      text: Markdown Examples
-      link: /markdown-examples
+      text: Installation
+      link: /installation
     - theme: alt
-      text: API Examples
-      link: /api-examples
-
+      text: Documentation
+      link: /quick-start
 features:
-  - title: Feature A
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature B
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
-  - title: Feature C
-    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Native Program Generation
+    details: |
+      Scripts compiled with Bunster are not just wrappers around your script, nor do they rely on any external shell on your system.
+  - title: Wite Once, Run Everywhere
+    details: Bunster offers static linking. Your scripts are compiled to a statically linked binary that runs on every machine.
+  - title: Module System
+    details: Bunsters's module system makes it easy to shares your scripts as a versioned modules to be used by others.
 ---
diff --git a/docs/installation.md b/docs/installation.md
@@ -0,0 +1,47 @@
+# Installation
+
+By default, **Bunster** is an independent utility that you can install and start using right away. However,
+**Bunster** does assume that you have [the Go toolchain](https://go.dev/dl) installed and accessbile in `PATH`.
+
+We rely on [gofmt](https://pkg.go.dev/cmd/gofmt) provided by the [the Go toolchain](https://go.dev/dl) to format the generated
+code. This makes it easy to debug and/or to learn from. Additionally, We use [the Go compiler](https://go.dev/dl) to compile
+the code and generate the executable for you.
+
+::: info
+The absence of [the Go toolchain](https://go.dev/dl) does not affect the working of **Bunster**. It's still going to work just fine.
+If you only care about the generated Go code, and don't want **Bunster** to automatically compile the exectuable for you.
+That is totally fine and you can go for it.
+:::
+
+
+## Docker Image
+The easiest way to get **Bunster** is through our official [Docker Image](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/).
+It comes with everything needed. Including the **Bunster** compiler and [the Go toolchain](https://go.dev/dl).
+
+```shell
+docker pull ghcr.io/yassinebenaid/bunster:latest
+```
+
+Or, if you want a specific version (v.0.3.0 for example):
+
+```shell
+docker pull ghcr.io/yassinebenaid/bunster:v0.3.0
+```
+
+## Using Go
+If you already have [the Go toolchain](https://go.dev/dl) installed. You can use the `go install` command to get **Bunster** on your machine.
+
+```shell
+go install github.com/yassinebenaid/bunster@latest
+```
+
+Or, if you want a specific version (v.0.3.0 for example):
+
+```shell
+go install github.com/yassinebenaid/bunster@v0.3.0
+```
+
+::: info
+If you choose to install using `go install`. make sure that `$HOME/go/bin` is added to your `PATH`. If not yet, Please add
+`export PATH=$PATH:$HOME/go/bin` to one of your profile files. eg. *`~/.bashrc` if you're using `bash`, or `~/.zshrc` if you're using `zsh`*.
+:::
diff --git a/docs/markdown-examples.md b/docs/markdown-examples.md
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -0,0 +1,14 @@
+# Quick Start
+
+Have you ever wished your shell scripts could be faster, more portable, and secure ?
+**Bunster** brings this to life by transforming your shell scripts into efficient,
+standalone binaries that are easy to distribute and deploy across platforms _(only unix is supported at the moment)_.
+
+Unlike other tools, **Bunster** doesn’t just wrap your scripts in a binary—it compiles them down to efficient native machine code,
+leveraging the powerful Go toolchain. This ensures performance, portability, and robustness.
+
+Technically speaking, **Bunster** is not a complete compiler, But rather a **Transplier** that generates **GO** code out of your scripts.
+Then, opionally uses the **Go Toolchain** to compile the code to an executable program.
+
+**Bunster** targets `bash` scripts in particular. The current syntax and features are all inherited from `bash`.
+other shells support will be added soon.
