docs(README,LICENSE): improve content, clean up formatting and extern…

…al links
osx-provisioner · Jun 9, 2021 · 6698b53 · 6698b53
1 parent 7697e6e
commit 6698b53
Show file tree

Hide file tree

Showing 3 changed files with 90 additions and 72 deletions.
diff --git a/README.md b/README.md
@@ -1,26 +1,40 @@
-# OSX Machine Profile Generator
+# Mac Maker Profile Generator
 
-## A Mac Maker Profile Development Environment.
-
-[Mac Maker](https://github.com/osx-provisioner/mac_maker) is a simply binary tool for configuring new Mac's with the software/tools you use every day.
-
-(Please see the [cookiecutter documentation](https://cookiecutter.readthedocs.io/) for instructions on how to use this project template.)
+[Mac Maker](https://github.com/osx-provisioner/mac_maker) is a single binary executable for configuring new Mac's with the software/tools you use every day.
 
 ##### Master Branch:
 [![profile-generator-self-test](https://github.com/osx-provisioner/profile-generator/actions/workflows/self-test.yml/badge.svg?branch=master)](https://github.com/osx-provisioner/profile-generator/actions/workflows/self-test.yml)
 
 ##### Production Branch:
 [![profile-generator-self-test](https://github.com/osx-provisioner/profile-generator/actions/workflows/self-test.yml/badge.svg?branch=production)](https://github.com/osx-provisioner/profile-generator/actions/workflows/self-test.yml)
 
-## About The Template Defaults
+## Quick Start Guide
+
+### 1. First make sure you're using Python 3.8 or later.
+- `pip install cookiecutter poetry`
+- `cookiecutter https://github.com/osx-provisioner/mac_maker.git --checkout v0.2.0`
+
+### 2. Give your project a name, and populate the other required template inputs.
+- [Cookiecutter](https://cookiecutter.readthedocs.io/) will prompt you to enter some information such as the Profile's name, and your GitHub user handle. 
+
+### 3. Wait for the Template to Render and the Virtual Environment to be Generated.
+- A [virtualenv](https://docs.python.org/3.8/library/venv.html) will be created for you automatically using [Poetry](https://python-poetry.org/).
+
+### 4. Start Customizing.
+- `cd <your new project director>`
+- `poetry shell` (to interact with the installed linting tools inside the virtualenv)
+
+## About This Template
 
-This template generates a development environment for the [Mac Maker](https://github.com/osx-provisioner/mac_maker.git) project, with functional CI/CD.
+This template uses a tool called [cookiecutter](https://cookiecutter.readthedocs.io/) to generate a Mac Maker Profile customized for you.
 
-The default profile has some excellent functionality out of the box:
-- Installs the [Homebrew](https://brew.sh/) and [Xcode](https://developer.apple.com/xcode/) cli tools automatically. (You may see some "Please Install Me" popups, safely ignore them and wait for your finished Mac.)
+The default configuration has some excellent functionality out of the box:
+- Installs the [Homebrew](https://brew.sh/) and [Xcode](https://developer.apple.com/xcode/) cli tools automatically.
+  - You may see a "Please Install Me" Xcode popup dialogue, safely ignore this and wait for your finished Mac.
 - A centralized package manifest in the [profile/vars/main.yml](./{{cookiecutter.profile_slug}}/profile/vars/main.yml) file.
 - A functional [ClamAV](https://github.com/Cisco-Talos/clamav) install to protect you against malicious downloads.
-- Node.js and Python, managed by [asdf](https://asdf-vm.com/#/). (Activate these language installs by following [these](https://asdf-vm.com/#/core-manage-asdf) instructions for your shell.)
+- Node.js and Python, managed by [asdf](https://asdf-vm.com/#/).
+  - Activate these language installs by following [these](https://asdf-vm.com/#/core-manage-asdf) instructions for your shell.
 - Easily mix and match Ansible roles in the [profile/install.yml](./{{cookiecutter.profile_slug}}/profile/install.yml) file.
 
 Use one of the many existing OSX Ansible roles to customize your installation:
@@ -30,28 +44,15 @@ Use one of the many existing OSX Ansible roles to customize your installation:
 
 Update your [profile/requirements.yml](./{{cookiecutter.profile_slug}}/profile/requirements.yml) file to add more [Ansible Galaxy](https://galaxy.ansible.com/) content as needed.
 
-## Quick Start Guide
-
-**First make sure you're using Python 3.8 or later.**
-
-- `pip install cookiecutter poetry`
-- `cookiecutter https://github.com/osx-provisioner/mac_maker.git --checkout v0.1.0`
-
-**Give your project a name, and populate the other required template inputs.**
-
-Once the templating is finished:
-- `cd <your new project director>`
-- `poetry shell` (to interact with the installed linting tools inside a virtualenv)
-
-A `master` branch will be created, allowing you to manage a separate `production` branch in [gitlabflow](https://docs.gitlab.com/ee/topics/gitlab_flow.html) style.
-
 ## License
 
 [GNU GPL](LICENSE)
 
-## Adding / Removing Dependencies For Your Project
+## Python Customization
+
+If for some reason you need to customize the Python development environment for the template, you can do so using [Poetry](https://python-poetry.org/).
 
-#### Python Dependencies:
+#### Managing Python Dependencies:
 
 Use the [pyproject.toml](./{{cookiecutter.profile_slug}}/pyproject.toml) file to store your project dependencies in accordance with [PEP 518](https://www.python.org/dev/peps/pep-0518/) and [Poetry Dependency Management](https://python-poetry.org/docs/pyproject/#dependencies-and-dev-dependencies).
 
@@ -73,4 +74,4 @@ Poetry is leveraged to manage the Python dependencies:
 Integrations with the following third party services are configured during templating:
 
 - [GitHub Workflows](https://docs.github.com/en/free-pro-team@latest/actions/reference/workflow-syntax-for-github-actions)
-  - [workflows](./{{cookiecutter.profile_slug}}/.github/workflows)
+  - The templated workflows can be found [here](./{{cookiecutter.profile_slug}}/.github/workflows).
diff --git a/{{cookiecutter.profile_slug}}/LICENSE b/{{cookiecutter.profile_slug}}/LICENSE
@@ -2,8 +2,21 @@ MIT License
 
 Copyright (c) 2021 {{ cookiecutter.author }}
 
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/{{cookiecutter.profile_slug}}/README.md b/{{cookiecutter.profile_slug}}/README.md
@@ -12,59 +12,63 @@
 
 Use [Mac Maker](https://github.com/osx-provisioner/mac_maker) to apply this profile to a Mac that is ready to setup.
 
-## About The Template Defaults
+## About The Default Configuration
 
 The template has generated you a development environment for a [Mac Maker](https://github.com/osx-provisioner/mac_maker.git) machine profile, with functional CI/CD.
 
-The default profile has some excellent functionality out of the box:
-- Installs the [Homebrew](https://brew.sh/) and [Xcode](https://developer.apple.com/xcode/) cli tools automatically. (You may see some "Please Install Me" popups, safely ignore them and wait for your finished Mac.)
+The default configuration has some excellent functionality out of the box:
+- Installs the [Homebrew](https://brew.sh/) and [Xcode](https://developer.apple.com/xcode/) cli tools automatically.
+  - You may see a "Please Install Me" Xcode popup dialogue, safely ignore this and wait for your finished Mac.
 - A centralized package manifest in the [profile/vars/main.yml](./profile/vars/main.yml) file.
-- A functional [ClamAV](https://github.com/Cisco-Talos/clamav) install to protect you against malicious downloads
-- Node.js and Python, managed by [asdf](https://asdf-vm.com/#/). (Activate these language installs by following [these](https://asdf-vm.com/#/core-manage-asdf) instructions for your shell.)
-- Easily mix and match Ansible Roles in the [profile/install.yml](./profile/install.yml) file
+- A functional [ClamAV](https://github.com/Cisco-Talos/clamav) install to protect you against malicious downloads.
+- Node.js and Python, managed by [asdf](https://asdf-vm.com/#/).
+  - Activate these language installs by following [these](https://asdf-vm.com/#/core-manage-asdf) instructions for your shell.
+- Easily mix and match Ansible roles in the [profile/install.yml](./profile/install.yml) file.
 
-## Default License
+#### Important Note about ClamAV on Catalina and Big Sur
 
-An [MIT](LICENSE) license has been generated for you by default, feel free to discard/change as you see fit.
+- To get the most out of your ClamAV install, make sure you grant it "Full Disk Access".
+- Please take a quick look at the documentation [here](https://github.com/osx-provisioner/role-clamav).
+
+## This Looks Complicated, How Can I Customize This?
+
+Start [here](./profile/vars/main.yml), it's really much simpler than you might think.
+
+## Making the Default Profile your Own
+
+To start branching out, and really customizing things, get familiar with the following files:
+
+ - [install.yml](profile/install.yml)           
+   - This is the main [ansible](https://ansible.com) playbook that will be run when you "Apply" this profile.
+ - [requirements.yml](profile/requirements.yml)
+   - This is configuration for [ansible-galaxy](https://galaxy.ansible.com/docs/using/installing.html#installing-multiple-roles-from-a-file) dependencies.
+   - If you add additional roles, include them here, so your Profile includes everything it needs.
+   - Make sure to read the documentation any new roles and add the required variables to your [main vars file](./profile/vars/main.yml).
 
-## Profile Folder
+## Configuration Files (More Complex Knob Tweaking)
 
-This repository has a [profile](profile) folder that contains the following required configuration, plus additional settings:
-
-| -- Filename ----------------| -- Description -------------------------------------------------------------- |
-|-----------------------------|-------------------------------------------------------------------------------|
-| [.ansible-lint](profile/.ansible-lint)       | configuration for [ansible-lint](https://ansible-lint.readthedocs.io/en/latest/)    |
-| [.yamllint](profile/.yamllint)               | configuration for [yamllint](https://yamllint.readthedocs.io/en/stable/)            |
-| [install.yml](profile/install.yml)           | the main [ansible](https://ansible.com) provisioning playbook that will be run      |
-| [requirements.yml](profile/requirements.yml) | configuration for [ansible-galaxy](https://galaxy.ansible.com/docs/using/installing.html#installing-multiple-roles-from-a-file) dependencies |
+There some configuration files you can fine tune as you see fit, they require more familiarity with Ansible:
+
+ - [.ansible-lint](profile/.ansible-lint)
+   - This is configuration for [ansible-lint](https://ansible-lint.readthedocs.io/en/latest/), which is used in the included GitHub CI pipeline.
+ - [.yamllint](profile/.yamllint)               
+   - This is configuration for [yamllint](https://yamllint.readthedocs.io/en/stable/), which is used in the included GitHub CI pipeline.
 
 ## Profile Precheck Folder
 
-The profile folder contains a special [__precheck__](profile/__precheck__) folder with configuration used by the provisioner to help end users apply the profile to their machines:
+The `profile` folder contains a special [__precheck__](profile/__precheck__) sub-folder with configuration used by [Mac Maker](https://github.com/osx-provisioner/mac_maker) to help end users apply the Profile to their machines.
 
-| -- Filename ----------------| -- Description -------------------------------------------------------------- |
-|-----------------------------|-------------------------------------------------------------------------------|
-| [env.yml](profile/__precheck__/env.yml)      | required environment variables that need to be set prior to installing this profile |
-| [notes.txt](profile/__precheck__/notes.txt)  | details about the installation visible to the end user                              |
+Please read the [Mac Maker Profile](https://mac-maker.readthedocs.io/en/latest/project/3.profiles.html) documentation for details on this. (It's a quick read.)
 
-## Development
+## Developing Your Profile
 
 [Mac Maker](https://github.com/osx-provisioner/mac_maker) can work with public GitHub repositories, or with `spec.json` files.
 
-A Mac Maker profile has a specific directory structure. The spec.json file lets you mix and match where the directories and files are. It's a bit inflexible in certain ways, because it requires absolute paths, but this makes it ideal to work off a USB stick or any portable media.
-
-```json
-{
-  "workspace_root_path": "The absolute path to the root folder of your cloned profile repository.",
-  "profile_data_path": "This absolute path usually points to the `profile` folder inside your profile repository.",
-  "galaxy_requirements_file": "This absolute path usually points to the `profile_data_path/requirements.yml` file inside your profile repository.",
-  "playbook": "This absolute path usually points to the `profile_data_path/install.yml` file inside your profile repository.",
-  "roles_path": [
-    "This absolute path usually points to the `profile_data_path/roles` folder inside your profile repository.",
-    "You can append several roles directories here, they should all be absolute paths."
-  ],
-  "inventory": "This absolute path usually points to the `profile_data_path/inventory` file inside your repository."
-}
-```
-
-When developing your profile locally, it's handy to setup a `spec.json` that points to all the locations you need, so you can just re-run Mac Maker to test.
+A Mac Maker Profile has a specific directory structure, but the `spec.json` file lets you mix and match where the directories and files are. It's a bit inflexible in certain ways, because it requires absolute paths, but this makes it ideal to work off a USB stick or any portable media.
+When developing your profile locally, it's handy to setup a `spec.json` file that points to all the locations you need, so you can just re-run Mac Maker to test.
+
+Please read the [Mac Maker Job Spec](https://mac-maker.readthedocs.io/en/latest/project/4.spec_files.html) documentation for details on this. (It's a quick read.)
+
+## Default License
+
+An [MIT](LICENSE) license has been generated for you by default, feel free to discard/change as you see fit.