Merge pull request #72 from basemate/introduce_scaffolder

Introduce scaffolder (documented & tested)

Author: jonasjabari

Gemfile

@@ -32,3 +32,7 @@ group :development, :test do
   gem 'byebug'
   gem 'webmock'
 end
+
+group :test do
+  gem "generator_spec"
+end

Gemfile.lock

@@ -99,6 +99,9 @@ GEM
     docile (1.3.1)
     erubi (1.7.1)
     ffi (1.9.25)
+    generator_spec (0.9.4)
+      activesupport (>= 3.0.0)
+      railties (>= 3.0.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
     haml (5.0.4)
@@ -250,6 +253,7 @@ DEPENDENCIES
   capybara
   cells-haml
   cells-rails
+  generator_spec
   matestack-ui-core!
   poltergeist
   puma

docs/README.md

@@ -6,9 +6,10 @@
 2. [Concepts](./concepts)
 3. [Core Components](./components)
 4. [Integrations](./integrations)
+5. [Tooling](./tooling_and_ecosystem)
 
 ## Diving deeper
 
-5. [Extend](./extend)
-6. [Architecture](./architecture)
-7. [Contribute](./contribute)
+6. [Extend](./extend)
+7. [Architecture](./architecture)
+8. [Contribute](./contribute)

docs/contribute/README.md

@@ -29,12 +29,9 @@ Tests follow quite the same rules as the documentation: Make sure to either add
 
 ## Release
 
-Webpacker is used for managing all JS assets. In order to deploy a packed JS, we
-use a "builder" app found in repo_root/builder
-This builder app uses a symlink in order to reference the actual core found in
-builder/vendor.
+Webpacker is used for managing all JS assets. In order to deploy a packed JS, we use a "builder" app found in `repo_root/builder`. This builder app uses a symlink in order to reference the actual core found in `builder/vendor`.
 
-You can run webpacker inside this builder app in order to pack JS assets:
+You can run webpacker inside this builder app to pack JS assets:
 
 ```shell
 cd builder

docs/extend/README.md

@@ -0,0 +1 @@
+# tbd

docs/tooling_and_ecosystem/generators/README.md

@@ -0,0 +1,19 @@
+# Create Matestack concepts using generators
+
+Those are extensions of the `Rails::Generators` and follow the same system as the classic Rails scaffolders. Reach out to us with feedback or if things don't behave the way you'd expect them to do!
+
+## General usage
+
+Create matestack apps, pages and components (and some corresponding parts, like routes and controllers) automatically from the command line!
+
+Each generator takes mandatory arguments and optional flags. Check their detailed description to see default parameters and the full list of options.
+
+Tests can be found [here](../../spec/lib/generators).
+
+**Note:** We recommend commiting or stashing your current changes so you see created/modified files within your application!
+
+Matestack App Generator is documented [here](./matestack_app_generator.md).
+
+Matestack Page Generator is documented [here](./matestack_page_generator.md).
+
+Matestack Component Generator is documented [here](./matestack_component_generator.md).

docs/tooling_and_ecosystem/generators/matestack_app_generator.md

@@ -0,0 +1,36 @@
+# Matestack App Generator
+
+## Usage
+
+Generates matestack apps to `app/matestack/apps`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack page in `app/matestack/apps/NAME.rb`.
+
+**--all_inclusive** - Optional. Also creates a corresponding matestack page, a controller with an action for the matestack page and a route to it.
+
+## Example 1
+
+```bash
+rails generate matestack_app example_app
+```
+
+Creates an ExampleApp in `app/matestack/apps/example_app.rb`.
+
+## Example 2
+
+```bash
+rails generate matestack_app simple_app --all_inclusive
+```
+
+Creates:
+- a SimpleApp in `app/matestack/apps/simple_app.rb`
+- an ExamplePage in `app/matestack/pages/simple_app/example_page.rb`
+- a SimpleAppController in `app/controllers/simple_app_controller.rb`
+- a route to `http://localhost:3000/simple_app/example_page`
+
+To see all options, run
+```bash
+rails generate matestack_app -h
+```

docs/tooling_and_ecosystem/generators/matestack_component_generator.md

@@ -0,0 +1,28 @@
+# Matestack Component Generator
+
+## Usage
+
+Generates matestack components to `app/matestack/components`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack component in `app/matestack/components/NAME.rb`.
+
+**--dynamic** - Optional. Makes the created component dynamic and also creates a corresponding `app/matestack/components/NAME.js` file.
+
+**--haml** - Optional. Creates a `app/matestack/components/NAME.haml` file to use 'normal' HTML tags.
+
+**--scss** - Optional. Creates an `app/matestack/components/NAME.scss` for custom component styling.
+
+## Example
+
+```bash
+rails generate matestack_component simple_component
+```
+
+Creates a SimpleComponent in `app/matestack/components/simple_component.rb`.
+
+To see all options, run
+```bash
+rails generate matestack_component -h
+```

docs/tooling_and_ecosystem/generators/matestack_page_generator.md

@@ -0,0 +1,52 @@
+# Matestack Page Generator
+
+## Usage
+
+Generates matestack pages to `app/matestack/pages`.
+
+## Parameters
+
+**NAME** - Mandatory. Creates an empty matestack page in `app/matestack/pages/NAME.rb`.
+
+**--app_name** - Mandatory. Adds a `/app_name` folder to `app/matestack/pages` to indicate to which matestack app the pages belongs. Pages _do not necessarily need to belong to an app_, but for now the page scaffolder can only provide this functionality.
+
+**--namespace** - Optional. Adds a `/namespace` folder within the `/app_name` and a namespace to the `page.rb`. You can also scope the namespace using additional `/`'s like so: `namespace_1/namespace_2`
+
+**--controller_action** - Optional. Takes a `controller#action` to use in the created route for the page. If not provided, a `controller#action` is created from **NAME** and **--app_name**.
+
+## Example 1
+
+```bash
+rails generate matestack_page simple_page --app_name example_app
+```
+
+Creates a SimplePage in `app/matestack/pages/example_app/simple_page.rb`.
+
+It also adds `get '#example_app/simple_page', to: 'example_app#simple_page'` to the `config/routes.rb` and proposes a
+```ruby
+def simple_page
+  responder_for(Pages::ExampleApp::SimplePage)
+end
+```
+in the terminal to use in your controller.
+
+## Example 2
+
+```bash
+rails generate matestack_page second_page --app_name example_app --namespace sample_namespace
+```
+
+Creates a SimplePage in `app/matestack/pages/example_app/sample_namespace/second_page.rb`.
+
+It also adds `get '#example_app/sample_namespace/second_page', to: 'example_app#second_page'` to the `config/routes.rb` and proposes a
+```ruby
+def simple_page
+  responder_for(Pages::ExampleApp::SampleNamespace::SecondPage)
+end
+```
+in the terminal to use in your, e.g., `example_app_controller.rb`.
+
+To see all options, run
+```bash
+rails generate matestack_page -h
+```

lib/generators/matestack_app/USAGE

@@ -0,0 +1,21 @@
+Description:
+    Stubs out a new matestack app. Pass the app name under_scored.
+
+    If you want so, pass the option '--all_inclusive' to also create
+    a corresponding matestack example_page, a controller, its action
+    and the route in 'config/routes.rb'.
+
+Example 1:
+    `rails generate matestack_app example_app`
+
+    This will create:
+        app/matestack/apps/example_app.rb
+
+Example 2:
+`rails generate matestack_app example_app --all_inclusive`
+
+    This will create:
+        app/matestack/apps/example_app.rb
+        app/matestack/pages/example_app/example_page.rb
+        app/controllers/example_app_controller.rb
+        route  get 'example_app/example_page', to: 'example_app#example_page'