Polish the code and add docs (#3)

Author: CodePrometheus

CHANGELOG.md

@@ -7,6 +7,7 @@ Release Notes.
 #### Features
 - Initialize the ruby agent core.
 - Implement e2e tests.
+- Add docs.
 
 #### Plugins
 * Support [Sinatra](https://github.com/sinatra/sinatra)

docs/README.md

@@ -2,6 +2,6 @@
 
 **This is the official documentation of SkyWalking Ruby agent. Welcome to the SkyWalking community!**
 
-SkyWalking Ruby is an open-source auto-instrument agent that provides support for
+SkyWalking Ruby is an open-source auto-instrument agent that provides support for distributed tracing across different frameworks within the Ruby language.
 
-distributed tracing across different frameworks within the Ruby language.
+This documentation covers a number of ways to set up the Ruby agent for various use cases.

docs/en/agent/plugins.md

@@ -0,0 +1,10 @@
+# Tracing Plugins
+
+The following plugins provide the distributed tracing capability, and the OAP backend would analyze the topology and
+metrics based on the tracing data.
+
+| Library                                       | Version  | Plugin Name |
+|:----------------------------------------------|:---------|:------------|
+| [redis](https://github.com/redis/redis-rb)    | ~> 5.0   | `redis`     |
+| [net-http](https://github.com/ruby/net-http)  | ~> 0.6.0 | `net_http`  |
+| [sinatra](https://github.com/sinatra/sinatra) | ~> 4.1   | `sinatra`   |

docs/en/development-and-contribution/how-to-release.md

@@ -143,6 +143,8 @@ Vote result should follow these:
 1. Publish to rubygems.org, this is optional for Apache releases, but we usually want to do this to let users use it conveniently.
 
   ```shell
+  gem build skywalking.gemspec
+  gem push skywalking.gemspec
   ```
 
 **NOTE**: please double check before publishing to rubygems.org, it's difficult to unpublish and republish the module at the moment.
@@ -169,11 +171,10 @@ Vote result should follow these:
     Website: http://skywalking.apache.org/
 
     SkyWalking Ruby Resources:
-- Issue: https://github.com/apache/skywalking/issues
+    Issue: https://github.com/apache/skywalking/issues
+
     - Mailing list: [email protected]
     - Documents: https://github.com/apache/skywalking-ruby/blob/v$VERSION/README.md
 
     The Apache SkyWalking Team
-```
-
-
+   ```

docs/en/setup/configuration.md

@@ -0,0 +1,106 @@
+# Quick Start
+
+## Requirements
+
+**SkyWalking Ruby agent requires SkyWalking 8.0+ and Ruby 3.0+**
+
+## Installing the gem
+
+The Ruby agent's gem is available from [RubyGems](https://rubygems.org/) as `skywalking`, we recommend you install and
+manage the skywalking gem dependency with [Bundler](http://bundler.io/), add the following line to your `Gemfile`, then
+run `bundle install` to install the gem.
+
+~~~ruby
+# Gemfile
+source "https://rubygems.org"
+
+gem "skywalking"
+~~~
+
+Besides, you can also make installation as simple as `gem install skywalking`.
+
+## Getting started with Rails
+
+You need to manually add `Skywalking.start` under config/initializers directory.
+
+Optionally the command `bundle exec rails generate skywalking:start`, will create a config file
+`config/initializers/skywalking.rb`, and then you can configure the start parameters.
+
+## Getting started with Sinatra
+
+You can list `gem 'skywalking'` after sinatra in your Gemfile and use `Bundler.require` during initialization or calling
+`require 'skywalking'` after sinatra gem is loaded, that is, skywalking gem needs to be after the other gems you
+require (e.g. redis, elasticsearch), like the following code:
+
+~~~ruby
+require 'redis'
+require 'sinatra'
+require 'skywalking'
+
+Skywalking.start
+
+get '/sw' do
+  "Hello, SkyWalking!"
+end
+~~~
+
+## Configuration
+
+You can configure the SkyWalking Ruby agent in various ways, the Ruby agent follows this order of precedence for
+configuration:
+
+- Defaults (please
+  see [DEFAULTS](https://github.com/apache/skywalking-ruby/blob/main/lib/skywalking/configuration.rb#L21))
+- Arguments to `Skywalking.start`
+- Configuration file (e.g. `conifg/skywalking.yml`)
+- Environment variables
+
+The following is an example of configuration at start:
+
+~~~ruby
+Skywalking.start(
+  service_name: 'sw-srv',
+  instance_name: 'sw-inst',
+  collector_backend_services: 'oap:11800'
+)
+~~~
+
+The following is an example of a configuration file:
+~~~yaml
+common: &defaults
+  service_name: Ruby-Agent-Common
+  log_level: debug
+
+development:
+  <<: *defaults
+  service_name: Ruby-Agent-Development
+
+test:
+  <<: *defaults
+  service_name: Ruby-Agent-Test
+
+production:
+  <<: *defaults
+  service_name: Ruby-Agent-Production
+~~~
+
+The following lists all the configuration options:
+
+| key                             | environment key                          | default value        | description                                                                                                                               |
+|---------------------------------|------------------------------------------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------|
+| service_name                    | SW_AGENT_SERVICE_NAME                    | Your_ApplicationName | The name of the service which showed in UI.                                                                                               |
+| instance_name                   | SW_AGENT_INSTANCE_NAME                   | Your_InstanceName    | To obtain the environment variable key for the instance name, if it cannot be obtained, an instance name will be automatically generated. |
+| namespace                       | SW_AGENT_NAMESPACE                       | Not set              | Namespace represents a subnet, such as kubernetes namespace, or 172.10..                                                                  |
+| environment                     | SW_AGENT_ENVIRONMENT                     | Not set              | The name of the environment this service is deployed in                                                                                   |
+| collector_backend_services      | SW_AGENT_COLLECTOR_BACKEND_SERVICES      | 127.0.0.1:11800      | Collector SkyWalking trace receiver service addresses.                                                                                    |
+| config_file                     | SW_AGENT_CONFIG_FILE                     | Not set              | The absolute path to the configuration file, if empty, it will automatically search for config/skywalking.yml in the root directory.      |
+| log_file_name                   | SW_AGENT_LOG_FILE_NAME                   | skywalking           | The name of the log file.                                                                                                                 |
+| log_file_path                   | SW_AGENT_LOG_FILE_PATH                   | Not set              | The path to the log file.                                                                                                                 |
+| log_level                       | SW_AGENT_LOG_LEVEL                       | info                 | The log level.                                                                                                                            |
+| disable_plugins                 | SW_AGENT_DISABLE_PLUGINS                 | Not set              | The plugins to disable.                                                                                                                   |
+| report_protocol                 | SW_AGENT_REPORT_PROTOCOL                 | grpc                 | The protocol to use for reporting.                                                                                                        |
+| re_ignore_operation             | SW_AGENT_RE_IGNORE_OPERATION             | Not set              | Ignore specific URL paths.                                                                                                                |
+| instance_properties_json        | SW_AGENT_INSTANCE_PROPERTIES_JSON        | Not set              | A custom JSON string to be reported as service instance properties, e.g. `{"key": "value"}`.                                              |
+| collector_heartbeat_period      | SW_AGENT_COLLECTOR_HEARTBEAT_PERIOD      | 30                   | he agent will send heartbeat to OAP every `collector_heartbeat_period` seconds.                                                           |
+| properties_report_period_factor | SW_AGENT_PROPERTIES_REPORT_PERIOD_FACTOR | 10                   | The agent will report service instance properties every `collector_heartbeat_period * properties_report_period_factor` seconds.           |
+| max_queue_size                  | SW_AGENT_MAX_QUEUE_SIZE                  | 10000                | The maximum queue size for reporting data.                                                                                                |

docs/en/setup/quick-start.md

@@ -14,36 +14,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-name: publish-docker
-
-on:
-  push:
-    branches:
-      - main
-
-env:
-  HUB: ghcr.io/apache/skywalking-ruby
-
-jobs:
-  build:
-    if: github.repository == 'apache/skywalking-ruby'
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      packages: write
-    timeout-minutes: 150
-    env:
-      VERSION: ${{ github.sha }}
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          submodules: true
-      - name: Log in to the Container registry
-        uses: docker/[email protected]
-        with:
-          registry: ${{ env.HUB }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-      - name: Polish docker image
-        run: |
-          make docker.push || make docker.push
+catalog:
+  - name: SkyWalking Ruby Overview
+    path: /readme
+  - name: Quick Start
+    path: /en/setup/quick-start
+  - name: Agent
+    catalog:
+      - name: Supported Plugins
+        path: /en/agent/plugins
+  - name: Development and Contribution
+    catalog:
+      - name: How to Release
+        path: /en/development-and-contribution/how-to-release
+  - name: Changelog
+    path: https://github.com/apache/skywalking-ruby/blob/master/CHANGELOG.md

.github/workflows/publish-docker.yaml renamed to docs/menu.yml

@@ -0,0 +1,47 @@
+#  Licensed to the Apache Software Foundation (ASF) under one or more
+#  contributor license agreements.  See the NOTICE file distributed with
+#  this work for additional information regarding copyright ownership.
+#  The ASF licenses this file to You under the Apache License, Version 2.0
+#  (the "License"); you may not use this file except in compliance with
+#  the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module Skywalking
+  class StartGenerator < ::Rails::Generators::Base
+    source_root File.join(File.dirname(__FILE__), 'templates')
+    desc 'Creates a skywalking initializer'
+
+    @namespace = "skywalking:start"
+
+    def copy_initializer
+      print_header
+      print_footer
+
+      template "skywalking_initializer.rb", "config/initializers/skywalking.rb"
+    end
+
+    private
+
+    def print_header
+      say ""
+      say shell.set_color "Welcome to the SkyWalking Ruby Agent instrumentation setup.", :green, :bold
+      say ""
+    end
+
+    def print_footer
+      say ""
+      say "You can configure skywalking start parameters by modifying config/initializers/skywalking.rb."
+      say ""
+      say "Thanks for using! Welcome to contribute to the SkyWalking community."
+      say ""
+    end
+  end
+end
+

examples/rails-demo/README.md

@@ -13,19 +13,4 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-require 'sinatra'
-require 'redis'
-require 'skywalking'
-
-Skywalking.start
-
-get '/sw' do
-  "Hello, SkyWalking!"
-end
-
-get '/hello/:name' do
-  redis = Redis.new(host: 'localhost', port: 6379)
-  redis.set('hello', 'world')
-  value = redis.get("hello")
-  "Hello #{value}!"
-end
+Skywalking.start