jekyll-theme-alta-docs 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e66de8ee1a3d8de337c6ab2214b84461339547390700443763ec32669f12e1ac
-  data.tar.gz: 407c33116e63d462aab77409f8161c614e189141565b4d6d690c2bf03581f007
+  metadata.gz: 594c6b0c645f5d4f641908e5348ba0a2a4cee23594d8b9c7d01dcaf3510b3d90
+  data.tar.gz: 4502b626ddf5cf2f4c1ae951eb80708eeae09a26cd23873d1b7047aaef89aca5
 SHA512:
-  metadata.gz: 68c991d1a43d1a76c4ed7d4a616f28b7e3efb10e45958d3c361aabf41768b831986bd4a4b9d26fe6840521ad04e5574749d4668bdd9b1455006e3a26537c2b04
-  data.tar.gz: b2e2567c5d572a406700f28e9fa91902ad5d60b15a1c98a3f18824aad5ffb1f50c9dc0da6d309c891b99fde090d3cf4e8fcc4ebb1af122e533e838800ea38710
+  metadata.gz: 37ee64aebf1b94aea5885f93792db8fc93c7df82ae2613e9759a6a7b0a00ca04aba7ac323b13a3f437d80e25076f7fdb4ec10e84fc060162adcaf9a67b458824
+  data.tar.gz: 35f9070c24010178cc30a0d755f0293f731cb72729b0854faee7bd9c2074fac22f07d43a005b0bde65ae465638629f97a7b29b30efca9df27980503824573e09

data/_includes/guidelines/rails/api_only_project_tree.md

@@ -0,0 +1,90 @@
+```
+|-- app
+|   |-- assets
+|   |   |-- (...)
+|   |
+|   |-- channels
+|   |   |-- (...)
+|   |
+|   |-- controllers
+|   |   |-- api
+|   |   |   |-- v1
+|   |   |   |   |-- base_controller.rb
+|   |   |   |-- api_controller.rb
+|   |   |-- concerns
+|   |   |   |-- .keep
+|   |   |-- application_controller.rb
+|   |
+|   |-- exceptions
+|   |   |-- .keep
+|   |
+|   |-- helpers
+|   |   |-- application_helper.rb
+|   |
+|   |-- jobs
+|   |   |-- application_job.rb
+|   |
+|   |-- lib
+|   |   |-- .keep
+|   |
+|   |-- mailers
+|   |   |-- application_mailer.rb
+|   |
+|   |-- models
+|   |   |-- (...)
+|   |
+|   |-- queries
+|   |   |-- .keep
+|   |
+|   |-- serializers
+|   |   |-- .keep
+|   |
+|   |-- services
+|   |   |-- .keep
+|   |
+|   |-- views
+|       |-- (...)
+|
+|-- bin
+|   |-- (...)
+|
+|-- config
+|   |-- (...)
+|
+|-- db
+|   |-- (...)
+|
+|-- lib
+|   |-- (...)
+|
+|-- log
+|   |-- (...)
+|
+|-- public
+|   |-- (...)
+|
+|-- storage
+|   |-- (...)
+|
+|-- storage
+|   |-- (...)
+|
+|-- test
+|   |-- (...)
+|
+|-- tmp
+|   |-- (...)
+|
+|-- vendor
+|   |-- (...)
+|
+|-- .env
+|-- .env.template
+|-- .gitignore
+|-- .rubocop.yml
+|-- .ruby-version
+|-- config.ru
+|-- Gemfile
+|-- Rakefile
+|-- README.md
+```

data/_includes/guidelines/rails/api_only_project_tree_with_files.md

@@ -0,0 +1,56 @@
+{% include guidelines/rails/api_only_project_tree.md %}
+
+
+**app/controllers/api/api_controller.rb**
+```ruby
+module Api
+  class ApiController < ActionController::API
+  end
+end
+```
+
+**app/controllers/api/v1/base_controller.rb**
+```ruby
+module Api
+  module V1
+    # Base API controller. It is used by other controllers in API/V1 directory.
+    class BaseController < Api::ApiController
+      # before_action :set_current_user
+      # before_action :check_blocked_user
+
+      # def send_response(status, message, code, data)
+      #   response = {
+      #     status: status,
+      #     message: message
+      #   }
+      #   response['data'] = data if data
+      #   response['code'] = code if code
+      #   render json: response, status: status
+      # end
+      #
+      # rescue_from Apipie::Error do |e|
+      #   send_response(
+      #     422,
+      #     e.message,
+      #     "ERR_#{controller_name}##{action_name}_INVALID_PARAM_#{e.param}".upcase,
+      #     nil
+      #   )
+      # end
+
+      # def set_current_user
+      #   @current_user_cognito = AwsCognitoService.new.get_current_user(request.headers['Authorization'])
+      #   @current_user = UserIdentity
+      #                   .includes(user_account: [:organization])
+      #                   .find_by(identity_id: @current_user_cognito.username)
+      #                   .user_account
+      # rescue StandardError => e
+      #   send_response(401, 'User unauthorized', 'ERR_USER_UNAUTHORIZED', { error: e })
+      # end
+      #
+      # def check_blocked_user
+      #   send_response(403, 'User unauthorized', 'ERR_USER_BLOCKED', nil) if @current_user.blocked?
+      # end
+    end
+  end
+end
+```

data/_includes/guidelines/rails/api_only_psql_no_admin_setup_instructions.md

@@ -0,0 +1,236 @@
+{% assign project_name = 'project-name' %}
+{% if include.project_name %}
+  {% assign project_name = include.project_name %}
+{% endif %}
+
+*Ruby: 2.6.5, Rails: 6.0.3*
+
+**Purpose:** Ruby on Rails API-only + PostgreSQL
+
+### Prerequisites
+
+* Ruby installed
+* Rails installed
+* Selected database installed (PostgreSQL, MySQL, etc.)
+
+### A) Set up Ruby on Rails project
+
+1. Create a project folder:
+
+        $ mkdir {{ project_name }}-api && cd {{ project_name }}-api
+
+2. Create Rails API-only project with PostgreSQL database:
+
+        $ rails new . --api --database postgresql
+
+3. Add gems:
+
+```ruby
+# Gemfile
+
+# Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin AJAX possible
+gem 'rack-cors'
+
+# API documentation
+gem 'apipie-rails'
+
+# Serializer
+gem 'active_model_serializers', '~> 0.10.0'
+
+# .ENV
+gem 'dotenv-rails'
+
+group :development, :test do
+  # Call 'byebug' anywhere in the code to stop execution and get a debugger console
+  gem 'byebug', platforms: [:mri, :mingw, :x64_mingw]
+  # Tests fixtures
+  gem 'factory_bot_rails'
+  # Tests coverage
+  gem 'simplecov', require: false
+  # Code analyzers
+  gem 'rails_best_practices'
+  gem 'rubocop-rails', require: false
+  gem 'rubycritic', require: false
+
+  gem 'minitest-hooks'
+end
+
+group :development do
+  # Catch security vulnerabilities
+  gem 'brakeman'
+  # Catch N+1 queries and unused eager loading
+  gem 'bullet'
+end
+```
+
+Other optional gems:
+
+```ruby
+# Gemfile
+
+# AWS SDK
+gem 'aws-sdk', '~> 3'
+gem 'aws-sdk-rails'
+
+# HTTP requests
+gem 'httparty'
+
+# Support PostGIS
+gem 'activerecord-postgis-adapter'
+
+# UI
+gem 'jquery-rails'
+gem 'select2-rails'
+
+```
+
+<div>
+4. Run:
+</div>
+
+      $ bundle install
+
+
+### B) Set up environment variables with .ENV
+
+1. Generate secret key:
+
+        $ rake secret
+
+2. Create `.env` file and add configuration:
+
+        APP_DB_USERNAME=db_username
+        APP_DB_PASSWORD=db_password
+        APP_DB_HOSTNAME=127.0.0.1
+        APP_DB_PORT=5432
+        SECRET_KEY_BASE=<paste here secret generate in the previous step>
+
+3. Create `.env` file template:
+
+        $ dotenv -t .env
+
+4. Add to `.gitignore`:
+
+        # Environment variables
+        .env
+        .env.prod
+        .env.dev
+
+        # Ignore Simplecov tests coverage results
+        coverage
+
+        # Ignore RDoc
+        doc
+
+        # Ignore Breakman output
+        brakeman_output.html
+
+### C) Set up database and run project
+
+1. Edit `config/database.yml`
+
+        pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
+        username: <%= ENV['APP_DB_USERNAME'] %>
+        password: <%= ENV['APP_DB_PASSWORD'] %>
+        port: <%= ENV['APP_DB_PORT'] %>
+        host: <%= ENV['APP_DB_HOSTNAME'] %>
+
+2. Create database and run migrations
+
+        $ rake db:create
+        $ rake db:migrate
+
+3. Run project
+
+        $ rails s
+        # OR
+        $ rails s -b xxx.xx.xxx.xx -p 4001
+
+4. Open website in the web browser.
+
+### D) Repository
+
+1. Create a new project and/or repository on Bitbucket, GitHub, etc.
+
+2. Run:
+
+        $ git add .
+        $ git commit -m "Ruby on Rails project setup."
+        $ git remote add origin <add repository URL>
+        $ git push -u origin master
+
+
+
+### E) Edit README.md file
+
+```markdown
+{% include templates/rails/rails_readme.md project_name=project_name %}
+```
+
+
+
+### F) Set up project tree
+
+Create folders and files in the project tree. Add empty `.keep` file to empty folders.
+
+{% include guidelines/rails/api_only_project_tree_with_files.md %}
+
+
+### G) Set up Gems and other
+
+
+#### UUID
+
+Add `config/initializers/generators.rb` file to set up database to use `uuid` as a primary key (ID):
+
+```ruby
+Rails.application.config.generators do |g|
+  g.orm :active_record, primary_key_type: :uuid
+end
+```
+
+
+#### Apipie
+
+Run:
+
+```
+$ rails g apipie:install
+```
+
+Edit `config/initializers/apipie.rb` file:
+
+```ruby
+Apipie.configure do |config|
+  config.app_name                = '{{ project_name }}'
+  config.api_base_url            = '/api/v1'
+  config.doc_base_url            = '/api/docs'
+  config.translate               = false
+  config.default_locale          = 'en'
+  config.languages               = ['en']
+  config.layout                  = 'apipie'
+  # where is your API defined?
+  config.api_controllers_matcher = File.join(Rails.root, 'app', 'controllers', '**', '*.rb') # rubocop:disable Rails/FilePath
+end
+```
+
+#### CORS
+
+Add/edit `config/initializers/cors.rb` file:
+
+```ruby
+Rails.application.config.middleware.insert_before 0, Rack::Cors do
+  allow do
+    origins '*'
+
+    resource '*',
+             headers: :any,
+             methods: %i[get post put patch delete options head]
+  end
+end
+```
+
+
+***
+
+After all, commit changes to the repository.

data/_includes/guidelines/rails/rails_cheatsheet.md

@@ -0,0 +1,275 @@
+### Basic commands
+---
+
+#### Run project
+
+``` bash
+$ rails s
+# OR
+$ rails s -b xxx.xxx.xx.xx -p yyyy
+```
+
+
+#### Database
+
+```bash
+$ rake db:create
+$ rake db:migrate
+$ rake db:rollback
+$ rake db:seed
+```
+
+#### Tests
+
+TODO
+
+#### Common tools, commands & scripts
+
+```bash
+# Rubocop
+$ rubocop --require rubocop-rails
+$ rubocop --require rubocop-rails -a  # with auto-correct
+$ rubocop --auto-correct --only FrozenStringLiteralComment # To fix frozen_string_literal
+
+
+# Rails best practices
+$ rails_best_practices .
+
+# Rubycritic
+$ bundle exec rubycritic --no-browser -f console
+
+# Breakman
+$ brakeman -o brakeman_output.html
+
+
+# Check also Bullet and code coverage with simplecov.
+```
+
+
+### Fixing issues
+---
+
+Some issues can be resolved by clearing the cache:
+
+```bash
+$ rake tmp:clear
+```
+
+... or restarting the spring:
+
+```bash
+$ spring stop
+```
+
+
+### Database login
+---
+
+```bash
+# PostgreSQL
+$ psql -U <user> -d <db_name> -h 127.0.0.1 -W
+
+# MySQL
+$ mysql -u <user> -h 127.0.0.1 -p <db_name>
+
+```
+
+
+### frozen_string_literal
+---
+
+Run following command to add `# frozen_string_literal: true` to all files:
+
+```bash
+$ bundle exec rubocop --auto-correct --only FrozenStringLiteralComment
+```
+
+### Gems
+---
+
+#### Apipie
+
+[Learn more](https://github.com/Apipie/apipie-rails)
+
+Apipie-rails is a DSL and Rails engine for documenting your RESTful API.
+
+*Setup*
+
+Run:
+
+```bash
+$ rails g apipie:install
+```
+
+Edit initializer: `config/initializers/apipie.rb`:
+
+```ruby
+Apipie.configure do |config|
+  config.app_name                = 'project-name'
+  config.api_base_url            = '/api/v1'
+  config.doc_base_url            = '/api/docs'
+  config.translate               = false
+  config.default_locale          = 'en'
+  config.languages               = ['en']
+  config.layout                  = 'apipie'
+  # where is your API defined?
+  config.api_controllers_matcher = File.join(Rails.root, 'app', 'controllers', '**', '*.rb') # rubocop:disable Rails/FilePath
+end
+```
+
+*Usage*
+
+Add Apipie comments to controllers' actions:
+
+```ruby
+api :GET, '/user', 'Get user data'
+error code: 401, desc: 'ERR_USER_UNAUTHORIZED: User is not authorized.'
+returns code: 200, desc: 'User data' do
+  property :status, String, desc: '200'
+  property :message, String, desc: 'User data'
+  property :data, Hash, desc: 'User data' do
+    property :id, String
+    property :email, String
+    property :organization, Hash do
+      property :id, String
+      property :name, String
+    end
+  end
+end
+def show
+  (...)
+end
+```
+
+Then, open in the web browser: `/api/docs`.
+
+
+
+#### Bullet
+
+[Learn more](https://github.com/flyerhzm/bullet)
+
+Helps to kill N+1 queries and unused eager loading
+
+*Usage*
+
+Bullet works by itself when server runs in development mode, logging warnings to the terminal and `/log/bullet.log`.
+
+
+#### Byebug
+
+[Learn more](https://github.com/deivid-rodriguez/byebug)
+
+Ruby debugger.
+
+*Usage*
+
+Add `byebug` to the code:
+
+```ruby
+def index
+  byebug
+  @articles = Article.find_recent
+end
+```
+
+**Basic commands**
+
+|Command|Description|
+|-------|-----------|
+|c|Continue|
+|q|Exit byebug|
+|n|Next breakpoint|
+|s|Next step (instruction)|
+
+
+
+#### Serializers
+
+[Learn more](https://github.com/rails-api/active_model_serializers)
+
+Serializes the data in responses.
+
+*Usage*
+
+Create a file for a resource in `app/serializers/<my_resource>_serializer.rb`:
+
+```ruby
+# MyResource serializer
+class MyResourceSerializer < ActiveModel::Serializer
+  attributes :id, :name, :color
+end
+```
+
+You can serialize data manually:
+
+```ruby
+MyResourceSerializer.new(@resource)
+```
+
+
+#### SimpleCov
+
+[Learn more](https://github.com/colszowka/simplecov)
+
+SimpleCov is a code coverage analysis tool for Ruby.
+
+*Usage*
+
+Run `RAILS_ENV='test' rake tests:run` and check coverage statistics.
+
+#### rails_best_practices
+
+[Learn more](https://github.com/flyerhzm/rails_best_practices)
+
+It is a code metric tool to check the quality of Rails code.
+
+*Usage*
+
+```
+rails_best_practices .
+```
+
+#### Rubycritic
+
+[Learn more](https://github.com/whitesmith/rubycritic)
+
+A Ruby code quality reporter.
+
+*Usage*
+
+```
+$ rubycritic
+$ rubycritic --no-browser
+$ rubycritic --no-browser -f console
+
+$ bundle exec rubycritic --no-browser -f console
+```
+
+#### Rubocop
+
+[Learn more](https://github.com/rubocop-hq/rubocop)
+
+A Ruby static code analyzer and code formatter.
+
+*Usage*
+
+```
+$ rubocop --require rubocop-rails
+
+$ rubocop --require rubocop-rails -a  # with auto-correct
+```
+
+#### Breakman
+
+[Learn more](https://github.com/presidentbeef/brakeman)
+
+Brakeman is a static analysis tool which checks Ruby on Rails applications for security vulnerabilities.
+
+*Usage*
+
+```
+$ brakeman
+
+$ brakeman -o brakeman_output.html
+```