Make cookbook directories clearer (#4217)

* Make directories clearer Signed-off-by: Ian Maddaus <[email protected]> * Update hugo_lint Signed-off-by: Ian Maddaus <[email protected]> * fix templates.md Signed-off-by: Ian Maddaus <[email protected]> * More minor corrections Signed-off-by: Ian Maddaus <[email protected]> * Additional fixes Signed-off-by: Ian Maddaus <[email protected]> * Additional fixes Signed-off-by: Ian Maddaus <[email protected]> * Proper indentation Signed-off-by: Ian Maddaus <[email protected]> --------- Signed-off-by: Ian Maddaus <[email protected]>
chef · Dec 11, 2023 · 765db48 · 765db48
1 parent a458f36
commit 765db48
Show file tree

Hide file tree

Showing 8 changed files with 220 additions and 286 deletions.
diff --git a/.expeditor/buildkite/hugo_lint.sh b/.expeditor/buildkite/hugo_lint.sh
@@ -2,18 +2,17 @@
 
 set -euo pipefail
 
-LINT_STATUS="$(grep -r -I --color=auto -o --with-filename -n -P '[^\x00-\x7F]' ./content | grep -v '[✓]'  &> /dev/null ; echo $?)"
+LINT_STATUS="$(grep -r -I --color=auto -o --with-filename -n -P '[^\x00-\x7F]' ./content | grep -v '[✓|├|─|│|└]' &> /dev/null ; echo $?)"
 
 if [ "$LINT_STATUS" == 1 ]; then
   echo "Success!"
   exit 0
 else
   echo "Failure!"
-  grep -r -I --color=auto -o --with-filename -n -P '[^\x00-\x7F]' ./content | grep  -v '[✓]'
+  grep -r -I --color=auto -o --with-filename -n -P '[^\x00-\x7F]' ./content | grep  -v '[✓|├|─|│|└]'
   if [ "$LINT_STATUS" == 0 ]; then
     exit 1
   else
     exit "$LINT_STATUS"
   fi
 fi
-
diff --git a/content/chef_repo.md b/content/chef_repo.md
@@ -11,7 +11,7 @@ aliases = ["/chef_repo.html"]
     parent = "chef_infra/cookbook_reference"
     weight = 15
 +++
-<!-- markdownlint-disable-file MD033 -->
+
 {{< readfile file="content/reusable/md/chef_repo_description.md" >}}
 
 ## Generate the chef-repo
@@ -28,94 +28,88 @@ chef generate repo REPO_NAME
 
 {{< /note >}}
 
-## Directory Structure
+## Directory structure
 
-The chef-repo contains several directories, each with a README file that describes what it is for and how to use that directory when managing systems.
+The chef-repo contains several directories, each with a README file that describes what it's for and how to use that directory when managing systems.
 
 The default structure of a new chef-repo is:
 
-```output
+```plain
 . chef-repo
-  - cookbooks
-    - README.md
-    - example
-      - attribtes
-        - default.rb
-      - recipes
-        - default.rb
-      - metadata.rb
-      - README.md
-  - data_bags
-      - example
-        - example_item.json
-      - README.md
-  - policyfiles
-      - README.md
-  - .chef-repo.txt
-  - chefignore
-  - License
-  - README.md
+├── LICENSE
+├── README.md
+├── chefignore
+├── cookbooks
+│   ├── README.md
+│   └── example
+│       ├── README.md
+│       ├── attributes
+│       │   ├── README.md
+│       │   └── default.rb
+│       ├── metadata.rb
+│       └── recipes
+│           ├── README.md
+│           └── default.rb
+├── data_bags
+│   ├── README.md
+│   └── example
+│       ├── README.md
+│       └── example_item.json
+└── policyfiles
+    └── README.md
 ```
 
-### cookbooks/
-
-This directory contains the cookbooks that are used to configure systems in the infrastructure which are are downloaded from the [Chef Supermarket](https://supermarket.chef.io/) or created locally. The Chef Infra Client uses cookbooks to configuring the systems in the organization. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.
+### cookbooks
 
-### data_bags/
+The `cookbooks` directory contains cookbooks that configure systems in the infrastructure which are are downloaded from the [Chef Supermarket](https://supermarket.chef.io/) or created locally. The Chef Infra Client uses cookbooks to configuring the systems in the organization. Each cookbook can be configured to contain cookbook-specific copyright, email, and license data.
 
-The `data_bags/` directory is used to store all the data bags that exist for an organization. Each sub-directory corresponds to a single data bag on the Chef Infra Server and contains a JSON file corresponding to each data bag item.
+### data_bags
 
-### policyfiles/
+The `data_bags` directory is used to store all the data bags that exist for an organization. Each sub-directory corresponds to a single data bag on the Chef Infra Server and contains a JSON file corresponding to each data bag item.
 
-The `policyfiles/` directory is used to store Policyfiles in the `.rb` format that define the set of cookbooks and attributes to apply to specific systems managed by the Chef Infra Server.
+### policyfiles
 
-## chefignore Files
+The `policyfiles` directory is used to store Policyfiles in the `.rb` format that define the set of cookbooks and attributes to apply to specific systems managed by the Chef Infra Server.
 
-The chefignore file is used to tell knife which cookbook files in the chef-repo should be ignored when uploading data to the Chef Infra Server. The type of data that should be ignored includes swap files, version control data, build output data, and so fort. The chefignore file uses the `File.fnmatch` Ruby syntax to define the ignore patterns using `*`, `**`, and `?` wildcards.
+### chefignore
 
-- A pattern is relative to the cookbook root
-- A pattern may contain relative directory names
-- A pattern may match all files in a directory
+A `chefignore` file tells knife which cookbook files in the chef-repo it should ignore when uploading data to the Chef Infra Server.
+Include swap files, version control data, and build output data in a `chefignore` file.
 
-The chefignore file can be located in any subdirectory of a chef-repo: `/`, `/cookbooks`, `/cookbooks/COOKBOOK_NAME/`, etc. It should contain sections similar to the following:
-
-```none
-## section
-*ignore_pattern
+The `chefignore` file has the following rules:
 
-## section
-ignore_pattern*
+- Patterns use `*`, `**`, and `?` wildcards to match files and directories as defined by the `File.fnmatch` Ruby method.
+- A pattern is relative to the directory it's included in.
+- A pattern may contain relative directory names.
+- A pattern may match all files in a directory.
+- You can add a `chefignore` file to any subdirectory of a chef-repo. For example, `/`, `/cookbooks`, `/cookbooks/COOKBOOK_NAME/`, etc.
+- Lines that start with `#` are comments.
 
-## section
-**ignore_pattern
+Group types of ignored files in sections similar to the following:
 
-## section
-ignore_pattern**
-
-## section
-?ignore_pattern
+```plain
+## OS generated files
+*ignore_pattern
 
-## section
-ignore_pattern?
+## Editors
+another_ignore_pattern*
 ```
 
-### Examples
-
-The following example shows how to add entries to the `chefignore` file.
+See Ruby's [`File.fnmatch` documentation](https://ruby-doc.org/core-2.5.1/File.html#method-c-fnmatch) for information on creating matching file patterns.
 
-#### Ignore editor swap files
+#### Examples
 
-Many text editors leave files behind. To prevent these files from being uploaded to the Chef Infra Server, add an entry to the `chefignore` file.
+Many text editors leave files behind. To prevent knife from uploading these files to the Chef Infra Server, add an entry to the `chefignore` file.
 
-For Emacs:
+For Emacs backup files:
 
-```none
+```plain
 *~
 ```
 
-and for vim:
+and for Vim swap files:
 
-```none
+```plain
 *.sw[a-z]
 ```
 

diff --git a/content/chef_solo.md b/content/chef_solo.md
@@ -28,16 +28,15 @@ cookbooks be added to an archive. For example:
 tar zcvf chef-solo.tar.gz ./cookbooks
 ```
 
-If multiple cookbook directories are being used, chef-solo expects the
+If you use multiple cookbook directories, chef-solo expects the
 tar.gz archive to have a directory structure similar to the following:
 
 ```text
-cookbooks/
-  |---- cbname1/
-    |--attributes/ ... etc
-  ...
-  |---- cbname2/
-    |--attributes/
+. cookbooks
+├── cookbook-name-1
+│   └── attributes
+└── cookbook-name-2
+    └── attributes
 ```
 
 The `cookbook_path` variable in the solo.rb file must include both
@@ -80,7 +79,7 @@ run-list. For example:
 }
 ```
 
-## Data Bags
+## Data bags
 
 A data bag is defined using JSON. chef-solo will look for data bags in
 `/var/chef/data_bags`, but this location can be modified by changing the

diff --git a/content/cookbook_repo.md b/content/cookbook_repo.md
@@ -29,16 +29,19 @@ chef generate repo REPO_NAME
 
 The default structure of the cookbooks directory is:
 
-```output
+```plain
 . chef-repo
-  - cookbooks
-    - example
-      - attributes
-        - default.rb
-      - recipes
-        - default.rb
-    - metadata.rb
-    - README.rb
+└── cookbooks
+    ├── README.md
+    └── example
+        ├── README.md
+        ├── attributes
+        │   ├── README.md
+        │   └── default.rb
+        ├── metadata.rb
+        └── recipes
+            ├── README.md
+            └── default.rb
 ```
 
 ## Cookbook Commands
@@ -65,21 +68,25 @@ The `custom_web` cookbook directory has the structure:
 
 ```text
 . cookbooks
-  - custom_web
-    - recipes
-      - default.rb
-    - test
-      - integration
-        - default
-          - default_test.rb
-    - .gitignore
-    - CHANGELOG.md
-    - chefignore
-    - kitchen.yml
-    - LICENSE
-    - metadata.rb
-    - Policyfile.rb
-    - README.md
+└── custom_web
+    ├── CHANGELOG.md
+    ├── LICENSE
+    ├── Policyfile.rb
+    ├── README.md
+    ├── chefignore
+    ├── compliance
+    │   ├── README.md
+    │   ├── inputs
+    │   ├── profiles
+    │   └── waivers
+    ├── kitchen.yml
+    ├── metadata.rb
+    ├── recipes
+    │   └── default.rb
+    └── test
+        └── integration
+            └── default
+                └── default_test.rb
 ```
 
 Any unneeded directory components can be left unused or deleted, if