docs: Standardize toplevel docs structure and readme (open-telemetry#418)

dazuma · web-flow · commit a20c7ce94867 · 2020-09-22T21:00:41.000-04:00
diff --git a/api/.yardopts b/api/.yardopts
@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry API
 --markup=markdown
---main=OVERVIEW.md
+--main=README.md
 ./lib/opentelemetry/**/*.rb
 ./lib/opentelemetry.rb
 -
-OVERVIEW.md
+README.md
 CHANGELOG.md
diff --git a/api/README.md b/api/README.md
diff --git a/exporter/jaeger/.yardopts b/exporter/jaeger/.yardopts
@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry Jaeger Exporter
 --markup=markdown
---main=OVERVIEW.md
+--main=README.md
 ./lib/opentelemetry/exporter/jaeger/**/*.rb
 ./lib/opentelemetry/exporter/jaeger.rb
 -
-OVERVIEW.md
+README.md
 CHANGELOG.md
diff --git a/exporter/otlp/.yardopts b/exporter/otlp/.yardopts
@@ -1,9 +1,9 @@
 --no-private
 --title=OpenTelemetry OTLP Exporter
 --markup=markdown
---main=OVERVIEW.md
+--main=README.md
 ./lib/opentelemetry/exporter/otlp/**/*.rb
 ./lib/opentelemetry/exporter/otlp.rb
 -
-OVERVIEW.md
+README.md
 CHANGELOG.md
diff --git a/instrumentation/all/.yardopts b/instrumentation/all/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Instrumentation All-in-one
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/all/**/*.rb
+./lib/opentelemetry/instrumentation/all.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/all/lib/opentelemetry/instrumentation/all.rb b/instrumentation/all/lib/opentelemetry/instrumentation/all.rb
@@ -16,6 +16,12 @@
 require 'opentelemetry-instrumentation-sidekiq'
 require 'opentelemetry-instrumentation-sinatra'
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   module Instrumentation
     # Namespace for the Opentelemetry all-in-one gem
diff --git a/instrumentation/all/opentelemetry-instrumentation-all.gemspec b/instrumentation/all/opentelemetry-instrumentation-all.gemspec
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/concurrent_ruby/.yardopts b/instrumentation/concurrent_ruby/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Concurrent Ruby Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/concurrent_ruby/lib/opentelemetry/instrumentation.rb b/instrumentation/concurrent_ruby/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/concurrent_ruby/opentelemetry-instrumentation-concurrent_ruby.gemspec b/instrumentation/concurrent_ruby/opentelemetry-instrumentation-concurrent_ruby.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/dalli/.yardopts b/instrumentation/dalli/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Dalli Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/dalli/README.md b/instrumentation/dalli/README.md
@@ -0,0 +1,49 @@
+# OpenTelemetry Dalli Instrumentation
+
+The OpenTelemetry Dalli gem is a community maintained instrumentation for the [Dalli][dalli-home] Memcache client.
+
+## How do I get started?
+
+Install the gem using:
+
+```
+gem install opentelemetry-instrumentation-dalli
+```
+
+Or, if you use [bundler][bundler-home], include `opentelemetry-instrumentation-dalli` in your `Gemfile`.
+
+## Usage
+
+To install the instrumentation, call `use` with the name of the instrumentation.
+
+```ruby
+OpenTelemetry::SDK.configure do |c|
+  c.use 'OpenTelemetry::Instrumentation::Dalli'
+end
+```
+
+Alternatively, you can also call `use_all` to install all the available instrumentation.
+
+```ruby
+OpenTelemetry::SDK.configure do |c|
+  c.use_all
+end
+```
+
+## How can I get involved?
+
+The `opentelemetry-instrumentation-dalli` gem source is [on github][repo-github], along with related gems including `opentelemetry-api` and `opentelemetry-sdk`.
+
+The OpenTelemetry Ruby gems are maintained by the OpenTelemetry-Ruby special interest group (SIG). You can get involved by joining us on our [gitter channel][ruby-gitter] or attending our weekly meeting. See the [meeting calendar][community-meetings] for dates and times. For more information on this and other language SIGs, see the OpenTelemetry [community page][ruby-sig].
+
+## License
+
+Apache 2.0 license. See [LICENSE][license-github] for more information.
+
+[dalli-home]: https://github.com/petergoldstein/dalli
+[bundler-home]: https://bundler.io
+[repo-github]: https://github.com/open-telemetry/opentelemetry-ruby
+[license-github]: https://github.com/open-telemetry/opentelemetry-ruby/blob/master/LICENSE
+[ruby-sig]: https://github.com/open-telemetry/community#ruby-sig
+[community-meetings]: https://github.com/open-telemetry/community#community-meetings
+[ruby-gitter]: https://gitter.im/open-telemetry/opentelemetry-ruby
diff --git a/instrumentation/dalli/lib/opentelemetry/instrumentation.rb b/instrumentation/dalli/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/dalli/opentelemetry-instrumentation-dalli.gemspec b/instrumentation/dalli/opentelemetry-instrumentation-dalli.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/ethon/.yardopts b/instrumentation/ethon/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Ethon Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/ethon/lib/opentelemetry/instrumentation.rb b/instrumentation/ethon/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/ethon/opentelemetry-instrumentation-ethon.gemspec b/instrumentation/ethon/opentelemetry-instrumentation-ethon.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/excon/.yardopts b/instrumentation/excon/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Excon Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/excon/lib/opentelemetry/instrumentation.rb b/instrumentation/excon/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/excon/opentelemetry-instrumentation-excon.gemspec b/instrumentation/excon/opentelemetry-instrumentation-excon.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['README.md', 'LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/faraday/.yardopts b/instrumentation/faraday/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Faraday Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/faraday/lib/opentelemetry/instrumentation.rb b/instrumentation/faraday/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/faraday/opentelemetry-instrumentation-faraday.gemspec b/instrumentation/faraday/opentelemetry-instrumentation-faraday.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/mysql2/.yardopts b/instrumentation/mysql2/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Mysql2 Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/mysql2/lib/opentelemetry/instrumentation.rb b/instrumentation/mysql2/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/mysql2/opentelemetry-instrumentation-mysql2.gemspec b/instrumentation/mysql2/opentelemetry-instrumentation-mysql2.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/net_http/.yardopts b/instrumentation/net_http/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Net::HTTP Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/net_http/lib/opentelemetry/instrumentation.rb b/instrumentation/net_http/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/net_http/opentelemetry-instrumentation-net_http.gemspec b/instrumentation/net_http/opentelemetry-instrumentation-net_http.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/rack/.yardopts b/instrumentation/rack/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Rack Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/rack/lib/opentelemetry/instrumentation.rb b/instrumentation/rack/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # Instrumentation should be able to handle the case when the library is not installed on a user's system.
   module Instrumentation
diff --git a/instrumentation/rack/opentelemetry-instrumentation-rack.gemspec b/instrumentation/rack/opentelemetry-instrumentation-rack.gemspec
@@ -21,7 +21,7 @@ Gem::Specification.new do |spec|
 
   spec.files = ::Dir.glob('lib/**/*.rb') +
                ::Dir.glob('*.md') +
-               ['LICENSE']
+               ['LICENSE', '.yardopts']
   spec.require_paths = ['lib']
   spec.required_ruby_version = '>= 2.5.0'
 
diff --git a/instrumentation/redis/.yardopts b/instrumentation/redis/.yardopts
@@ -0,0 +1,9 @@
+--no-private
+--title=OpenTelemetry Redis Instrumentation
+--markup=markdown
+--main=README.md
+./lib/opentelemetry/instrumentation/**/*.rb
+./lib/opentelemetry/instrumentation.rb
+-
+README.md
+CHANGELOG.md
diff --git a/instrumentation/redis/lib/opentelemetry/instrumentation.rb b/instrumentation/redis/lib/opentelemetry/instrumentation.rb
@@ -4,6 +4,12 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+# OpenTelemetry is an open source observability framework, providing a
+# general-purpose API, SDK, and related tools required for the instrumentation
+# of cloud-native software, frameworks, and libraries.
+#
+# The OpenTelemetry module provides global accessors for telemetry objects.
+# See the documentation for the `opentelemetry-api` gem for details.
 module OpenTelemetry
   # "Instrumentation" are specified by
   # https://github.com/open-telemetry/opentelemetry-specification/blob/784635d01d8690c8f5fcd1f55bdbc8a13cf2f4f2/specification/glossary.md#instrumentation-library
diff --git a/instrumentation/redis/opentelemetry-instrumentation-redis.gemspec b/instrumentation/redis/opentelemetry-instrumentation-redis.gemspec
diff --git a/instrumentation/restclient/.yardopts b/instrumentation/restclient/.yardopts
diff --git a/instrumentation/restclient/README.md b/instrumentation/restclient/README.md
diff --git a/instrumentation/restclient/lib/opentelemetry/instrumentation.rb b/instrumentation/restclient/lib/opentelemetry/instrumentation.rb
diff --git a/instrumentation/restclient/opentelemetry-instrumentation-restclient.gemspec b/instrumentation/restclient/opentelemetry-instrumentation-restclient.gemspec
diff --git a/instrumentation/sidekiq/.yardopts b/instrumentation/sidekiq/.yardopts
diff --git a/instrumentation/sidekiq/lib/opentelemetry/instrumentation.rb b/instrumentation/sidekiq/lib/opentelemetry/instrumentation.rb
diff --git a/instrumentation/sidekiq/opentelemetry-instrumentation-sidekiq.gemspec b/instrumentation/sidekiq/opentelemetry-instrumentation-sidekiq.gemspec
diff --git a/instrumentation/sinatra/.yardopts b/instrumentation/sinatra/.yardopts
diff --git a/instrumentation/sinatra/lib/opentelemetry/instrumentation.rb b/instrumentation/sinatra/lib/opentelemetry/instrumentation.rb
diff --git a/instrumentation/sinatra/opentelemetry-instrumentation-sinatra.gemspec b/instrumentation/sinatra/opentelemetry-instrumentation-sinatra.gemspec
diff --git a/resource_detectors/.yardopts b/resource_detectors/.yardopts
diff --git a/resource_detectors/lib/opentelemetry/resource/detectors.rb b/resource_detectors/lib/opentelemetry/resource/detectors.rb
diff --git a/resource_detectors/opentelemetry-resource_detectors.gemspec b/resource_detectors/opentelemetry-resource_detectors.gemspec
diff --git a/sdk/.yardopts b/sdk/.yardopts
