diff --git a/docs/api/api.rst b/docs/api/index.rst
similarity index 100%
rename from docs/api/api.rst
rename to docs/api/index.rst
diff --git a/docs/examples/index.rst b/docs/examples/index.rst
new file mode 100644
index 00000000000..92fc679b701
--- /dev/null
+++ b/docs/examples/index.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+Examples
+========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ **
diff --git a/docs/exporter/index.rst b/docs/exporter/index.rst
new file mode 100644
index 00000000000..df1d06294d3
--- /dev/null
+++ b/docs/exporter/index.rst
@@ -0,0 +1,11 @@
+:orphan:
+:hidden:
+
+Exporters
+=========
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ **
diff --git a/docs/faq-and-cookbook.rst b/docs/faq-and-cookbook.rst
deleted file mode 100644
index 2aacb3eeb4f..00000000000
--- a/docs/faq-and-cookbook.rst
+++ /dev/null
@@ -1,136 +0,0 @@
-Frequently Asked Questions and Cookbook
-=======================================
-
-This page answers frequently asked questions, and serves as a cookbook
-for common scenarios.
-
-Create a new span
------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
-
- tracer = trace.get_tracer(__name__)
- with tracer.start_as_current_span("print") as span:
- print("foo")
- span.set_attribute("printed_string", "foo")
-
-Getting and modifying a span
-----------------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
-
- current_span = trace.get_current_span()
- current_span.set_attribute("hometown", "seattle")
-
-Create a nested span
---------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
- import time
-
- tracer = trace.get_tracer(__name__)
-
- # Create a new span to track some work
- with tracer.start_as_current_span("parent"):
- time.sleep(1)
-
- # Create a nested span to track nested work
- with tracer.start_as_current_span("child"):
- time.sleep(2)
- # the nested span is closed when it's out of scope
-
- # Now the parent span is the current span again
- time.sleep(1)
-
- # This span is also closed when it goes out of scope
-
-
-Capturing baggage at different contexts
----------------------------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
-
- tracer = trace.get_tracer(__name__)
- with tracer.start_as_current_span(name="root span") as root_span:
- parent_ctx = baggage.set_baggage("context", "parent")
- with tracer.start_as_current_span(
- name="child span", context=parent_ctx
- ) as child_span:
- child_ctx = baggage.set_baggage("context", "child")
-
- print(baggage.get_baggage("context", parent_ctx))
- print(baggage.get_baggage("context", child_ctx))
-
-Manually setting span context
------------------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
- from opentelemetry.trace import NonRecordingSpan, SpanContext, TraceFlags
- from opentelemetry.sdk.trace import TracerProvider
- from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
- from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
-
- trace.set_tracer_provider(TracerProvider())
- trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
-
- tracer = trace.get_tracer(__name__)
-
- # Extracting from carrier header
- carrier = {'traceparent': '00-a9c3b99a95cc045e573e163c3ac80a77-d99d251a8caecd06-01'}
- ctx = TraceContextTextMapPropagator().extract(carrier=carrier)
-
- with tracer.start_as_current_span('child', context=ctx) as span:
- span.set_attribute('primes', [2, 3, 5, 7])
-
- # Or if you have a SpanContext object already.
- span_context = SpanContext(
- trace_id=2604504634922341076776623263868986797,
- span_id=5213367945872657620,
- is_remote=True,
- trace_flags=TraceFlags(0x01)
- )
- ctx = trace.set_span_in_context(NonRecordingSpan(span_context))
-
- with tracer.start_as_current_span("child", context=ctx) as span:
- span.set_attribute('evens', [2, 4, 6, 8])
-
-Using multiple tracer providers with different Resource
--------------------------------------------------------
-
-.. code-block:: python
-
- from opentelemetry import trace
- from opentelemetry.sdk.trace import TracerProvider
- from opentelemetry.sdk.resources import Resource
- from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
-
- # Global tracer provider which can be set only once
- trace.set_tracer_provider(
- TracerProvider(resource=Resource.create({"service.name": "service1"}))
- )
- trace.get_tracer_provider().add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
-
- tracer = trace.get_tracer(__name__)
- with tracer.start_as_current_span("some-name") as span:
- span.set_attribute("key", "value")
-
-
-
- another_tracer_provider = TracerProvider(
- resource=Resource.create({"service.name": "service2"})
- )
- another_tracer_provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
-
- another_tracer = trace.get_tracer(__name__, tracer_provider=another_tracer_provider)
- with another_tracer.start_as_current_span("name-here") as span:
- span.set_attribute("another-key", "another-value")
diff --git a/docs/getting-started.rst b/docs/getting-started.rst
deleted file mode 100644
index c4db11c24a2..00000000000
--- a/docs/getting-started.rst
+++ /dev/null
@@ -1,253 +0,0 @@
-Getting Started
-===============
-
-This guide walks you through instrumenting a Python application with ``opentelemetry-python``.
-
-For more elaborate examples, see `examples `_.
-
-Hello world: emit a trace to your console
----------------------------------------------
-
-To get started, install both the opentelemetry API and SDK:
-
-.. code-block:: sh
-
- pip install opentelemetry-api
- pip install opentelemetry-sdk
-
-The API package provides the interfaces required by the application owner, as well
-as some helper logic to load implementations.
-
-The SDK provides an implementation of those interfaces. The implementation is designed to be generic and extensible enough
-that in many situations, the SDK is sufficient.
-
-Once installed, you can use the packages to emit spans from your application. A span
-represents an action within your application that you want to instrument, such as an HTTP request
-or a database call. Once instrumented, you can extract helpful information such as
-how long the action took. You can also add arbitrary attributes to the span that provide more insight for debugging.
-
-The following example script emits a trace containing three named spans: "foo", "bar", and "baz":
-
-.. literalinclude:: getting_started/tracing_example.py
- :language: python
- :lines: 15-
-
-When you run the script you can see the traces printed to your console:
-
-.. code-block:: sh
-
- $ python tracing_example.py
- {
- "name": "baz",
- "context": {
- "trace_id": "0xb51058883c02f880111c959f3aa786a2",
- "span_id": "0xb2fa4c39f5f35e13",
- "trace_state": "{}"
- },
- "kind": "SpanKind.INTERNAL",
- "parent_id": "0x77e577e6a8813bf4",
- "start_time": "2020-05-07T14:39:52.906272Z",
- "end_time": "2020-05-07T14:39:52.906343Z",
- "status": {
- "status_code": "OK"
- },
- "attributes": {},
- "events": [],
- "links": []
- }
- {
- "name": "bar",
- "context": {
- "trace_id": "0xb51058883c02f880111c959f3aa786a2",
- "span_id": "0x77e577e6a8813bf4",
- "trace_state": "{}"
- },
- "kind": "SpanKind.INTERNAL",
- "parent_id": "0x3791d950cc5140c5",
- "start_time": "2020-05-07T14:39:52.906230Z",
- "end_time": "2020-05-07T14:39:52.906601Z",
- "status": {
- "status_code": "OK"
- },
- "attributes": {},
- "events": [],
- "links": []
- }
- {
- "name": "foo",
- "context": {
- "trace_id": "0xb51058883c02f880111c959f3aa786a2",
- "span_id": "0x3791d950cc5140c5",
- "trace_state": "{}"
- },
- "kind": "SpanKind.INTERNAL",
- "parent_id": null,
- "start_time": "2020-05-07T14:39:52.906157Z",
- "end_time": "2020-05-07T14:39:52.906743Z",
- "status": {
- "status_code": "OK"
- },
- "attributes": {},
- "events": [],
- "links": []
- }
-
-Each span typically represents a single operation or unit of work.
-Spans can be nested, and have a parent-child relationship with other spans.
-While a given span is active, newly-created spans inherit the active span's trace ID, options, and other attributes of its context.
-A span without a parent is called the root span, and a trace is comprised of one root span and its descendants.
-
-In this example, the OpenTelemetry Python library creates one trace containing three spans and prints it to STDOUT.
-
-Configure exporters to emit spans elsewhere
--------------------------------------------
-
-The previous example does emit information about all spans, but the output is a bit hard to read.
-In most cases, you can instead *export* this data to an application performance monitoring backend to be visualized and queried.
-It's also common to aggregate span and trace information from multiple services into a single database, so that actions requiring multiple services can still all be visualized together.
-
-This concept of aggregating span and trace information is known as distributed tracing. One such distributed tracing backend is known as Jaeger. The Jaeger project provides an all-in-one Docker container with a UI, database, and consumer.
-
-Run the following command to start Jaeger:
-
-.. code-block:: sh
-
- docker run -p 16686:16686 -p 6831:6831/udp jaegertracing/all-in-one
-
-This command starts Jaeger locally on port 16686 and exposes the Jaeger thrift agent on port 6831. You can visit Jaeger at http://localhost:16686.
-
-After you spin up the backend, your application needs to export traces to this system. Although ``opentelemetry-sdk`` doesn't provide an exporter
-for Jaeger, you can install it as a separate package with the following command:
-
-.. code-block:: sh
-
- pip install opentelemetry-exporter-jaeger
-
-After you install the exporter, update your code to import the Jaeger exporter and use that instead:
-
-.. literalinclude:: getting_started/jaeger_example.py
- :language: python
- :lines: 15-
-
-Finally, run the Python script:
-
-.. code-block:: python
-
- python jaeger_example.py
-
-You can then visit the Jaeger UI, see your service under "services", and find your traces!
-
-Instrumentation example with Flask
-------------------------------------
-
-While the example in the previous section is great, it's very manual. The following are common actions you might want to track and include as part of your distributed tracing.
-
-* HTTP responses from web services
-* HTTP requests from clients
-* Database calls
-
-To track these common actions, OpenTelemetry has the concept of instrumentations. Instrumentations are packages designed to interface
-with a specific framework or library, such as Flask and psycopg2. You can find a list of the currently curated extension packages in the `Contrib repository `_.
-
-Instrument a basic Flask application that uses the requests library to send HTTP requests. First, install the instrumentation packages themselves:
-
-.. code-block:: sh
-
- pip install opentelemetry-instrumentation-flask
- pip install opentelemetry-instrumentation-requests
-
-
-The following small Flask application sends an HTTP request and also activates each instrumentation during its initialization:
-
-.. literalinclude:: getting_started/flask_example.py
- :language: python
- :lines: 15-
-
-
-Now run the script, hit the root URL (http://localhost:5000/) a few times, and watch your spans be emitted!
-
-.. code-block:: sh
-
- python flask_example.py
-
-
-Configure Your HTTP propagator (b3, Baggage)
--------------------------------------------------------
-
-A major feature of distributed tracing is the ability to correlate a trace across
-multiple services. However, those services need to propagate information about a
-trace from one service to the other.
-
-To enable this propagation, OpenTelemetry has the concept of `propagators `_,
-which provide a common method to encode and decode span information from a request and response, respectively.
-
-By default, ``opentelemetry-python`` is configured to use the `W3C Trace Context `_
-and `W3C Baggage `_ HTTP headers for HTTP requests, but you can configure it to leverage different propagators. Here's
-an example using Zipkin's `b3 propagation `_:
-
-.. code-block:: sh
-
- pip install opentelemetry-propagator-b3
-
-Following the installation of the package containing the b3 propagator, configure the propagator as follows:
-
-.. code-block:: python
-
- from opentelemetry.propagate import set_global_textmap
- from opentelemetry.propagators.b3 import B3Format
-
- set_global_textmap(B3Format())
-
-Use the OpenTelemetry Collector for traces
-------------------------------------------
-
-Although it's possible to directly export your telemetry data to specific backends, you might have more complex use cases such as the following:
-
-* A single telemetry sink shared by multiple services, to reduce overhead of switching exporters.
-* Aggregating traces across multiple services, running on multiple hosts.
-
-To enable a broad range of aggregation strategies, OpenTelemetry provides the `opentelemetry-collector `_.
-The Collector is a flexible application that can consume trace data and export to multiple other backends, including to another instance of the Collector.
-
-Start the Collector locally to see how the Collector works in practice. Write the following file:
-
-.. code-block:: yaml
-
- # /tmp/otel-collector-config.yaml
- receivers:
- otlp:
- protocols:
- grpc:
- http:
- exporters:
- logging:
- loglevel: debug
- processors:
- batch:
- service:
- pipelines:
- traces:
- receivers: [otlp]
- exporters: [logging]
- processors: [batch]
-
-Then start the Docker container:
-
-.. code-block:: sh
-
- docker run -p 4317:4317 \
- -v /tmp/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
- otel/opentelemetry-collector:latest \
- --config=/etc/otel-collector-config.yaml
-
-Install the OpenTelemetry Collector exporter:
-
-.. code-block:: sh
-
- pip install opentelemetry-exporter-otlp
-
-Finally, execute the following script:
-
-.. literalinclude:: getting_started/otlpcollector_example.py
- :language: python
- :lines: 15-
diff --git a/docs/index.rst b/docs/index.rst
index 4344bab2ba0..c01557463ff 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,117 +1,44 @@
-OpenTelemetry-Python
-====================
-
-The Python `OpenTelemetry `_ client.
+OpenTelemetry Python API Reference
+==================================
.. image:: https://img.shields.io/badge/slack-chat-green.svg
:target: https://cloud-native.slack.com/archives/C01PD4HUVBL
:alt: Slack Chat
+Welcome to the **API docs** for the `Python OpenTelemetry client
+`_.
-This documentation describes the :doc:`opentelemetry-api `,
-:doc:`opentelemetry-sdk `, and several `integration packages <#integrations>`_.
-
-The library is currently stable for tracing. Support for :doc:`metrics ` and
-:doc:`logging ` are currently under development and are considered experimental.
-
-Requirement
------------
-OpenTelemetry-Python supports Python 3.6 and higher.
-
-Installation
-------------
-
-The API and SDK packages are available on PyPI, and can installed via pip:
-
-.. code-block:: sh
-
- pip install opentelemetry-api
- pip install opentelemetry-sdk
-
-In addition, there are several extension packages which can be installed separately as::
-
- pip install opentelemetry-exporter-{exporter}
- pip install opentelemetry-instrumentation-{instrumentation}
+For an introduction to OpenTelemetry, see the `OpenTelemetry website docs
+`_.
-These are for exporter and instrumentation packages respectively.
-The Jaeger, Zipkin, OTLP and OpenCensus Exporters can be found in the :scm_web:`exporter `
-directory of the repository. Instrumentations and additional exporters can be found in the
-`Contrib repo instrumentation `_
-and `Contrib repo exporter `_ directories.
+To learn how to instrument your Python code, see `Getting Started
+`_. For
+project status, information about releases, installation instructions and more,
+see `Python `_.
-Extensions
-----------
-
-Visit `OpenTelemetry Registry `_ to find
-related projects like exporters, instrumentation libraries, tracer implementations, etc.
-
-Installing Cutting Edge Packages
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-While the project is pre-1.0, there may be significant functionality that
-has not yet been released to PyPI. In that situation, you may want to
-install the packages directly from the repo. This can be done by cloning the
-repository and doing an `editable
-install `_:
-
-.. code-block:: sh
-
- git clone https://github.com/open-telemetry/opentelemetry-python.git
- cd opentelemetry-python
- pip install -e ./opentelemetry-api
- pip install -e ./opentelemetry-sdk
+Getting Started
+---------------
-
-.. toctree::
- :maxdepth: 1
- :caption: Getting Started
- :name: getting-started
-
- getting-started
- faq-and-cookbook
+* `Getting Started `_
+* `Frequently Asked Questions and Cookbook `_
.. toctree::
:maxdepth: 1
:caption: Core Packages
:name: packages
- api/api
- sdk/sdk
-
-.. toctree::
- :maxdepth: 2
- :caption: Exporters
- :name: exporters
- :glob:
-
- exporter/**
+ api/index
+ sdk/index
.. toctree::
:maxdepth: 2
- :caption: Shims
- :name: Shims
- :glob:
-
- shim/**
-
-.. toctree::
- :maxdepth: 1
- :caption: Performance
- :name: performance-tests
- :glob:
-
- performance/**
-
-.. toctree::
- :maxdepth: 1
- :caption: Examples
- :name: examples
+ :caption: More
:glob:
- examples/**
+ exporter/index
+ shim/index
+ examples/index
-Indices and tables
-------------------
* :ref:`genindex`
* :ref:`modindex`
diff --git a/docs/performance/benchmarks.rst b/docs/performance/benchmarks.rst
deleted file mode 100644
index 9c406c0323f..00000000000
--- a/docs/performance/benchmarks.rst
+++ /dev/null
@@ -1,4 +0,0 @@
-Performance Tests - Benchmarks
-==============================
-
-Click `here `_ to view the latest performance benchmarks for packages in this repo.
diff --git a/docs/sdk/sdk.rst b/docs/sdk/index.rst
similarity index 100%
rename from docs/sdk/sdk.rst
rename to docs/sdk/index.rst
diff --git a/docs/shim/index.rst b/docs/shim/index.rst
new file mode 100644
index 00000000000..5fad3b36639
--- /dev/null
+++ b/docs/shim/index.rst
@@ -0,0 +1,10 @@
+:orphan:
+
+Shims
+=====
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ **