Update yaml format in docs (#1496)

CONTRIBUTING.md

@@ -5,10 +5,9 @@ We love pull requests. Here's a quick guide:
 2. Run the tests. We only take pull requests with passing tests, and it's great to know that you have a clean slate: `bundle && bundle exec rake`
 
 3. We are using [Rubocop](https://github.com/bbatsov/rubocop) because we love static code analyzers. 
-
-Ways to run Rubocop:
-- `bundle exec rubocop`
-- `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer.
+    * Ways to run Rubocop:
+        - `bundle exec rubocop`
+        - `bundle exec rake` would run the test suite and after that it runs the Ruby static code analyzer.
 
 4. Please add a test for your change. Only refactoring and documentation changes require no new tests. If you are adding functionality or fixing a bug, we need a test! We use [Minitest](https://github.com/seattlerb/minitest) in this project.
 
@@ -49,7 +48,26 @@ If you're reviewing a PR, you should ask yourself:
 * Prefer `&&`, `||` over `and`, `or`.
 * `MyClass.my_method(my_arg)` not `my_method( my_arg )` or `my_method my_arg`.
 * `a = b` and not `a=b`.
-* Follow the conventions you see used in the source already.
+* use dash syntax for yaml arrays:
+```Yaml
+# this
+a_things:
+  - small_thing
+  - big_thing
+  - other_thing
+
+# instead of these: 
+b_things: [small_thing, big_thing, other_thing]
+c_things: [
+  small_thing,
+  big_thing,
+  other_thing,
+]
+
+# If in doubt, `bundle exec rake reformat_yaml['lib/path/to/file.yml']`
+```
+* In general, follow the conventions you see used in the source already.
+* **ALL SHALL OBEY THE RUBOCOP**
 
 ### Tips
 

README.md

@@ -252,17 +252,32 @@ and you can then override or add elements to suit your needs. See more about how
 use locales [here](lib/locales/README.md)
 
 ```yaml
-
 en-au-ocker:
   faker:
     name:
       # Existing faker field, new data
-      first_name: [Charlotte, Ava, Chloe, Emily]
+      first_name: 
+        - Charlotte
+        - Ava
+        - Chloe
+        - Emily
 
       # New faker fields
-      ocker_first_name: [Bazza, Bluey, Davo, Johno, Shano, Shazza]
-      region: [South East Queensland, Wide Bay Burnett, Margaret River, Port Pirie, Gippsland, Elizabeth, Barossa]
-
+      ocker_first_name: 
+        - Bazza 
+        - Bluey
+        - Davo
+        - Johno
+        - Shano
+        - Shazza
+      region:
+        - South East Queensland
+        - Wide Bay Burnett
+        - Margaret River
+        - Port Pirie
+        - Gippsland
+        - Elizabeth
+        - Barossa
 ```
 
 ## Contributing

lib/locales/README.md

@@ -4,38 +4,37 @@ The default locale is English. You can see how it is implemented in the "transla
 
 Here's how to set it:
 
-```
+```ruby
 # Sets the locale to "Simplified Chinese":
-
 Faker::Config.locale = 'zh-CN'
 ```
 
 It works so that once the Faker locale is set to a different location, the translate method will check that .yml file for an equivalent and use that data. If it doesn't exist, it defaults back to English. It uses the "i18n" gem to do this.
 
 Using Chinese as an example, when the locale is set to Chinese and you attempt to call for hipster ipsem (which doesn't exist at the time of this writing), you will get English back. It checks the "zh-CH.yml" file, does not find "hipster" and then checks the "en.yml" file and returns a word from that array.
 
-```
+```ruby
 Faker::Config.locale = 'zh-CN'
-
 Faker::Hipster.word #=> "kogi"
 ```
 
 In order to update a locale with more translation features, simply add a new field to the .yml file that corresponds to an existing piece of functionality in the "en.yml" file. In this example, that would mean providing Chinese hipster words.
 
-```
+```yaml
 # /lib/locales/zh-CN.yml
+hipster:
+    - "屌丝"
+```
 
-hipster: ["屌丝"]
-
+```ruby
 # Now this should work:
-
 Faker::Hipster.word #=> "屌丝"
 ```
 
 After you've done that, find or create a test file for the locale you've updated and test the functionality for that language.
 
 In our hypothetical example here, one would add something like this to the "test-zh-locale.rb" file in the "test_ch_methods" method:
 
-```
+```ruby
 assert Faker::Hipster.word.is_a? String
 ```

tasks/reformat_yaml.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+desc 'Reformat a yaml file into a common format'
+task :reformat_yaml, [:filename] do |_, args|
+  args.with_defaults(filename: nil)
+
+  if args[:filename].nil?
+    raise ArgumentError, 'A filename is required. `bundle exec rake reformat_yaml["lib/path/to/fil"]`'
+  end
+
+  root_dir = File.absolute_path(File.join(__dir__, '..'))
+  target_file = File.join(root_dir, args[:filename])
+  reformat_file(target_file)
+end
+
+def reformat_file(filename)
+  puts "reformatting #{filename}"
+
+  input = YAML.load_file(filename)
+  output = input.to_yaml
+
+  output.sub!(/^---\n/, '') # remove header
+
+  File.write(filename, output)
+end

unreleased_README.md

@@ -308,17 +308,32 @@ and you can then override or add elements to suit your needs. See more about how
 use locales [here](lib/locales/README.md)
 
 ```yaml
-
 en-au-ocker:
   faker:
     name:
       # Existing faker field, new data
-      first_name: [Charlotte, Ava, Chloe, Emily]
+      first_name: 
+        - Charlotte
+        - Ava
+        - Chloe
+        - Emily
 
       # New faker fields
-      ocker_first_name: [Bazza, Bluey, Davo, Johno, Shano, Shazza]
-      region: [South East Queensland, Wide Bay Burnett, Margaret River, Port Pirie, Gippsland, Elizabeth, Barossa]
-
+      ocker_first_name: 
+        - Bazza 
+        - Bluey
+        - Davo
+        - Johno
+        - Shano
+        - Shazza
+      region:
+        - South East Queensland
+        - Wide Bay Burnett
+        - Margaret River
+        - Port Pirie
+        - Gippsland
+        - Elizabeth
+        - Barossa
 ```
 
 ## Contributing