documentation

CONTRIBUTING.md

@@ -24,13 +24,19 @@ If you have a bug fix, performance improvement, feature addition, documentation
 
 ### Coding
 
+#### Dart
+
 It does not really matter what editor you use; however, if you want to contribute to the Dart codebase and do not want to set up Dart on your local machine, you can use a containerized development environment with all of the requirements built-in. Here are two options:
 
 1. Gitpod. This repo has a Gitpod config already setup, so all you have to do is visit: https://gitpod.io/#https://github.com/nyoungstudios/alfa. Or replace my GitHub url with your fork.
 2. VS Code's dev container. In order to use this, clone your fork to your local machine and follow this [setup guide](https://code.visualstudio.com/docs/remote/containers) before opening the folder in VS Code. In short, you will need to install Docker and the [VS Code Remote Containers extension](https://aka.ms/vscode-remote/download/containers). Finally, when opening the repo in VS Code, it will prompt you to open it in the dev container. Then, it will build the Docker image with all the dependencies needed.
 
 To build the Dart executable, just run `make` from the repository's root directory. Then, run the `./rename.sh` script to rename the executable to the filename the `install.sh` script expects.
 
+#### Entries (Bash script functions)
+
+If you like to contribute a new entry with a function to install something, you can run this script `./tools/create_function.sh entry_name` from the repo's root directory to create the boilerplate code. For the guidelines and best practices for writing your function, please see the example [here](functions/_example/).
+
 ### Style
 
 This respository uses EditorConfig to define the number of spaces for indentation as well as removing excess white characters. A lot of editors come bundled with native support, but if not you can always install an EditorConfig extension. For more information, visit their [website](https://editorconfig.org). Additionally, if you are using VS Code and are contributing to the Dart codebase, this repo includes a `settings.json` file with the recommended Dart style guidelines.

README.md

@@ -30,7 +30,7 @@ Config files are defined as `toml` files. This has the benefits of JSON, but fri
 
 The schema for the config file can be found [here](docs/ConfigSchema.md).
 
-All the installation scripts are bash scripts, and they are defined in the [functions.sh](functions.sh) file. This script includes the functions to install popular tools such as brew, Oh My Zsh (and plugins), Anaconda, NVM, Docker, and much more! The documentation for all of the things you can install (along with its input arguments) can be found [here](docs/entries/). If there is not a function to install your favorite tool(s), it is easy to extend the bash script with a new function (and open a PR with your contribution).
+All the different things that you can install are defined in the [functions](functions/) folder. Take a look at the `README.md` for each of the function entries to see how to add them to your configuration file and what options to pass to it. The built-in functions includes the ability to install popular tools such as brew, Oh My Zsh (and plugins), Anaconda, NVM, Docker, and much more! If there is not an entry to install your favorite tool(s), it is easy to add a new entry - just run `./tools/create_function.sh entry_name` from the repository's root directory to get started.
 
 ### Install list file
 

docs/ConfigSchema.md

@@ -15,7 +15,7 @@ options = []
 
 ### Name
 
-The `name` field refers to the `name` field in the `dictionary.toml` file. Looking at the `dictionary.toml` file, you can find the associated bash function that is called in the `functions.sh` file. The name field is also what you would put in the install list file (passed with the `-f` argument in the `install.sh` script). Alternatively, you can always write a more friendly name in the `tags` array. See the next section for more detail on that.
+The `name` field refers any of the folder names in the [functions](../functions/) directory. Read the `README.md` file within each of the folders and/or take a look at the `install.sh` file to see what any given entry does upon being called. The name field in your config is also what you would put in the install list file (passed with the `-f` argument in the `install.sh` script). Alternatively, you can always write a more friendly name in the `tags` array. See the next section for more detail on that.
 
 If you like to call a function more than once, but with different options; then, you can append a plus sign after the name followed by a string to help you remember what that entry does (sort of like email address aliases). This is so we do not have duplicate keys within the dictionary in the toml file. For example, if we wanted to call the `apt_get_packages` function twice, we could do something like this.
 

docs/InstallListSchema.md

@@ -30,3 +30,10 @@ name
 // name2
 custom
 ```
+
+And in this case, only these items would be installed:
+```txt
+name
+item1
+item2
+```

functions/_example/config.toml

@@ -1 +1,8 @@
+# The value of the "install_function" key references the bash function name in install.sh
+# If you want to run the function in sudo mode, add `sudo = true`
+# If you want have separate functions for macos and linux, you can nest the "install_function"
+# and "sudo" keys under the operating system name. It will look something like this:
+#
+# linux.install_function = "install_example_linux"
+# macos.install_function = "install_example_macos"
 install_function = "install_example"

tools/create_function.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# Usage: ./tools/create_function.sh function_name
+# Usage: ./tools/create_function.sh entry_name
 
 set -eu
 
@@ -10,14 +10,14 @@ if [[ ! -f "install.sh" ]]; then
 fi
 
 if [[ -z "$1" ]]; then
-  echo "must past the function name as the first argument"
+  echo "must past the entry name as the first argument"
   exit 1
 fi
 
 folder="functions/$1"
 
 if [[ -f "$folder/install.sh" || -f "$folder/config.toml" || -f "$folder/README.md" ]]; then
-  echo "a function with the name \"$1\" already exists"
+  echo "an entry with the name \"$1\" already exists"
   exit 1
 fi
 
@@ -61,4 +61,4 @@ EOF
 )
 echo "$README" > "$folder/README.md"
 
-echo "Created function with name $1 in $folder"
+echo "Created an entry with name $1 in $folder"