Add readTheDocs (#252)

Co-authored-by: Aaron Abbott <aaronabbott@google.com>
Co-authored-by: alrex <aboten@lightstep.com>

.github/workflows/test.yml

@@ -85,7 +85,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        tox-environment: [ "docker-tests", "lint" ]
+        tox-environment: [ "docker-tests", "lint", "docs" ]
     name: ${{ matrix.tox-environment }}
     runs-on: ubuntu-latest
     steps:

.readthedocs.yml

@@ -0,0 +1,14 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+
+build:
+  image: latest
+
+python:
+  version: 3.9
+  install:
+    - requirements: docs-requirements.txt

docs-requirements.txt

@@ -0,0 +1,35 @@
+sphinx~=2.4
+sphinx-rtd-theme~=0.4
+sphinx-autodoc-typehints~=1.10.2
+
+# Need to install the api/sdk in the venv for autodoc. Modifying sys.path
+# doesn't work for pkg_resources.
+-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-api&subdirectory=opentelemetry-api"
+-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-sdk&subdirectory=opentelemetry-sdk"
+
+# Required by opentelemetry-instrumentation
+fastapi~=0.58.1
+psutil~=5.7.0
+pymemcache~=1.3
+
+-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-instrumentation&subdirectory=opentelemetry-instrumentation"
+
+# Required by conf
+django>=2.2
+
+# Required by instrumentation packages
+aiohttp~=3.0
+aiopg>=0.13.0
+asyncpg>=0.12.0
+boto~=2.0
+botocore~=1.0
+celery>=4.0
+flask~=1.0
+grpcio~=1.27
+mysql-connector-python~=8.0
+pymongo~=3.1
+PyMySQL~=0.9.3
+pyramid>=1.7
+redis>=2.6
+sqlalchemy>=1.0
+ddtrace>=0.34.0

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -0,0 +1,179 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+
+import os
+import sys
+from configparser import ConfigParser
+from os import listdir
+from os.path import isdir, join
+
+# configure django to avoid the following exception:
+# django.core.exceptions.ImproperlyConfigured: Requested settings, but settings
+# are not configured. You must either define the environment variable
+# DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
+from django.conf import settings
+
+settings.configure()
+
+exp = "../exporter"
+exp_dirs = [
+    os.path.abspath("/".join(["../exporter", f, "src"]))
+    for f in listdir(exp)
+    if isdir(join(exp, f))
+]
+
+instr = "../instrumentation"
+instr_dirs = [
+    os.path.abspath("/".join(["../instrumentation", f, "src"]))
+    for f in listdir(instr)
+    if isdir(join(instr, f))
+]
+
+sdk_ext = "../sdk-extension"
+sdk_ext_dirs = [
+    os.path.abspath("/".join(["../sdk-extension", f, "src"]))
+    for f in listdir(sdk_ext)
+    if isdir(join(sdk_ext, f))
+]
+
+sys.path[:0] = exp_dirs + instr_dirs + sdk_ext_dirs
+
+# -- Project information -----------------------------------------------------
+
+project = "OpenTelemetry Python Contrib"
+copyright = "OpenTelemetry Authors"  # pylint: disable=redefined-builtin
+author = "OpenTelemetry Authors"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Easy automatic cross-references for `code in backticks`
+default_role = "any"
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    # API doc generation
+    "sphinx.ext.autodoc",
+    # Support for google-style docstrings
+    "sphinx.ext.napoleon",
+    # Infer types from hints instead of docstrings
+    "sphinx_autodoc_typehints",
+    # Add links to source from generated docs
+    "sphinx.ext.viewcode",
+    # Link to other sphinx docs
+    "sphinx.ext.intersphinx",
+    # Add a .nojekyll file to the generated HTML docs
+    # https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing
+    "sphinx.ext.githubpages",
+    # Support external links to different versions in the Github repo
+    "sphinx.ext.extlinks",
+]
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3/", None),
+    "opentracing": (
+        "https://opentracing-python.readthedocs.io/en/latest/",
+        None,
+    ),
+    "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
+    "wrapt": ("https://wrapt.readthedocs.io/en/latest/", None),
+    "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
+    "opentelemetry": (
+        "https://opentelemetry-python.readthedocs.io/en/latest/",
+        None,
+    ),
+}
+
+# http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky
+# Sphinx will warn about all references where the target cannot be found.
+nitpicky = True
+# Sphinx does not recognize generic type TypeVars
+# Container supposedly were fixed, but does not work
+# https://github.com/sphinx-doc/sphinx/pull/3744
+nitpick_ignore = []
+
+cfg = ConfigParser()
+cfg.read("./nitpick-exceptions.ini")
+mcfg = cfg["default"]
+
+
+def getlistcfg(strval):
+    return [
+        val.strip()
+        for line in strval.split("\n")
+        for val in line.split(",")
+        if val.strip()
+    ]
+
+
+if "class_references" in mcfg:
+    class_references = getlistcfg(mcfg["class_references"])
+    for class_reference in class_references:
+        nitpick_ignore.append(("py:class", class_reference,))
+
+if "anys" in mcfg:
+    anys = getlistcfg(mcfg["anys"])
+    for any in anys:
+        nitpick_ignore.append(("any", any,))
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+    "member-order": "bysource",
+}
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+
+# Support external links to specific versions of the files in the Github repo
+branch = os.environ.get("READTHEDOCS_VERSION")
+if branch is None or branch == "latest":
+    branch = "master"
+
+REPO = "open-telemetry/opentelemetry-python-contrib/"
+scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch
+scm_web = "https://github.com/" + REPO + "blob/" + branch
+
+# Store variables in the epilogue so they are globally available.
+rst_epilog = """
+.. |SCM_WEB| replace:: {s}
+.. |SCM_RAW_WEB| replace:: {sr}
+.. |SCM_BRANCH| replace:: {b}
+""".format(
+    s=scm_web, sr=scm_raw_web, b=branch
+)
+
+# used to have links to repo files
+extlinks = {
+    "scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"),
+    "scm_web": (scm_web + "/%s", "scm_web"),
+}

docs/exporter/datadog/datadog.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Datadog Exporter
+==============================
+
+.. automodule:: opentelemetry.exporter.datadog
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/index.rst

@@ -0,0 +1,93 @@
+OpenTelemetry-Python-Contrib
+============================
+
+Complimentary instrumentation and vendor-specific packages for use with the
+Python `OpenTelemetry <https://opentelemetry.io/>`_ client.
+
+.. image:: https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python
+   :target: https://gitter.im/open-telemetry/opentelemetry-python
+   :alt: Gitter Chat
+
+
+**Please note** that this library is currently in _beta_, and shouldn't
+generally be used in production environments.
+
+Installation
+------------
+
+There are several complimentary packages available on PyPI which can be
+installed separately via pip:
+
+.. code-block:: sh
+
+    pip install opentelemetry-exporter-{exporter}
+    pip install opentelemetry-instrumentation-{instrumentation}
+    pip install opentelemetry-sdk-extension-{sdkextension}
+
+A complete list of packages can be found at the 
+`Contrib repo instrumentation <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/instrumentation>`_
+and `Contrib repo exporter <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/exporter>`_ directories.
+
+Extensions
+----------
+
+Visit `OpenTelemetry Registry <https://opentelemetry.io/registry/?s=python>`_ to
+find a lit of 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 <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_:
+
+.. code-block:: sh
+
+    git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
+    cd opentelemetry-python-contrib
+    pip install -e ./instrumentation/opentelemetry-instrumentation-flask
+    pip install -e ./instrumentation/opentelemetry-instrumentation-botocore
+    pip install -e ./sdk-extension/opentelemetry-sdk-extension-aws
+
+
+.. toctree::
+    :maxdepth: 2
+    :caption: OpenTelemetry Exporters
+    :name: exporters
+    :glob:
+
+    exporter/**
+
+.. toctree::
+    :maxdepth: 2
+    :caption: OpenTelemetry Instrumentations
+    :name: Instrumentations
+    :glob:
+
+    instrumentation/**
+
+.. toctree::
+    :maxdepth: 2
+    :caption: OpenTelemetry Performance
+    :name: Performance
+    :glob:
+
+    performance/**
+
+.. toctree::
+    :maxdepth: 2
+    :caption: OpenTelemetry SDK Extensions
+    :name: SDK Extensions
+    :glob:
+
+    sdk-extension/**
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/instrumentation/aiohttp_client/aiohttp_client.rst

@@ -0,0 +1,7 @@
+OpenTelemetry aiohttp client Instrumentation
+============================================
+
+.. automodule:: opentelemetry.instrumentation.aiohttp_client
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/aiopg/aiopg.rst

@@ -0,0 +1,7 @@
+OpenTelemetry aiopg Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.aiopg
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/asgi/asgi.rst

@@ -0,0 +1,9 @@
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-asgi/README.rst
+
+API
+---
+
+.. automodule:: opentelemetry.instrumentation.asgi
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/asyncpg/asyncpg.rst

@@ -0,0 +1,10 @@
+OpenTelemetry asyncpg Instrumentation
+=====================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.instrumentation.asyncpg
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/boto/boto.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Boto Instrumentation
+==================================
+
+.. automodule:: opentelemetry.instrumentation.boto
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/botocore/botocore.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Botocore Instrumentation
+======================================
+
+.. automodule:: opentelemetry.instrumentation.botocore
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/celery/celery.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Celery Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.celery
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/dbapi/dbapi.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Database API Instrumentation
+==========================================
+
+.. automodule:: opentelemetry.instrumentation.dbapi
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/django/django.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Django Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.django
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/fastapi/fastapi.rst

@@ -0,0 +1,9 @@
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-fastapi/README.rst
+
+API
+---
+
+.. automodule:: opentelemetry.instrumentation.fastapi
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/flask/flask.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Flask Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.flask
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/grpc/grpc.rst

@@ -0,0 +1,10 @@
+OpenTelemetry gRPC Instrumentation
+==================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.instrumentation.grpc
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/instrumentation/jinja2/jinja2.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Jinja2 Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.jinja2
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/mysql/mysql.rst

@@ -0,0 +1,7 @@
+OpenTelemetry MySQL Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.mysql
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/psycopg2/psycopg2.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Psycopg Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.psycopg2
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/pymemcache/pymemcache.rst

@@ -0,0 +1,7 @@
+OpenTelemetry pymemcache Instrumentation
+========================================
+
+.. automodule:: opentelemetry.instrumentation.pymemcache
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/pymongo/pymongo.rst

@@ -0,0 +1,7 @@
+OpenTelemetry pymongo Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pymongo
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/pymysql/pymysql.rst

@@ -0,0 +1,7 @@
+OpenTelemetry PyMySQL Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pymysql
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/pyramid/pyramid.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Pyramid Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pyramid
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/redis/redis.rst

@@ -0,0 +1,7 @@
+OpenTelemetry Redis Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.redis
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/requests/requests.rst

@@ -0,0 +1,7 @@
+OpenTelemetry requests Instrumentation
+======================================
+
+.. automodule:: opentelemetry.instrumentation.requests
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/sqlalchemy/sqlalchemy.rst

@@ -0,0 +1,7 @@
+OpenTelemetry SQLAlchemy Instrumentation
+========================================
+
+.. automodule:: opentelemetry.instrumentation.sqlalchemy
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/sqlite3/sqlite3.rst

@@ -0,0 +1,7 @@
+OpenTelemetry SQLite3 Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.sqlite3
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/starlette/starlette.rst

@@ -0,0 +1,9 @@
+.. include:: ../../../instrumentation/opentelemetry-instrumentation-starlette/README.rst
+
+API
+---
+
+.. automodule:: opentelemetry.instrumentation.starlette
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/system_metrics/system_metrics.rst

@@ -0,0 +1,7 @@
+OpenTelemetry System Metrics Instrumentation
+============================================
+
+.. automodule:: opentelemetry.instrumentation.system_metrics
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/instrumentation/wsgi/wsgi.rst

@@ -0,0 +1,7 @@
+OpenTelemetry WSGI Instrumentation
+==================================
+
+.. automodule:: opentelemetry.instrumentation.wsgi
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

docs/nitpick-exceptions.ini

@@ -0,0 +1,30 @@
+[default]
+class_references=
+    ; TODO: Understand why sphinx is not able to find this local class
+    opentelemetry.trace.propagation.textmap.TextMapPropagator
+    ; - AwsXRayFormat
+    opentelemetry.trace.propagation.textmap.DictGetter
+    ; - instrumentation.asgi.CarrierGetter
+    ; API
+    opentelemetry.trace.propagation.textmap.Getter
+    ; - DatadogFormat
+    ; - AWSXRayFormat
+    TextMapPropagatorT
+    ; - AwsXRayFormat.extract
+
+anys=
+    ; API
+    opentelemetry.trace.propagation.textmap.TextMapPropagator.fields
+    ; - AWSXRayFormat
+    TraceId
+    ; - AwsXRayIdsGenerator
+    TraceIdRatioBased
+    ; - AwsXRayIdsGenerator
+    ; SDK
+    SpanProcessor
+    ; - DatadogExportSpanProcessor
+    TracerProvider
+    ; - AwsXRayIdsGenerator
+    ; Instrumentation
+    BaseInstrumentor
+    ; - instrumentation.*

docs/performance/benchmarks.rst

@@ -1,4 +1,4 @@
 Performance Tests - Benchmarks
 ==============================
 
-Click `here <https://open-telemetry.github.io/opentelemetry-python-contrib/benchmarks/index.html>_` to view the latest performance benchmarks for packages in this repo.
+Click `here <https://open-telemetry.github.io/opentelemetry-python-contrib/benchmarks/index.html>`_ to view the latest performance benchmarks for packages in this repo.

docs/sdk-extension/aws/aws.rst

@@ -0,0 +1,12 @@
+OpenTelemetry Python - AWS SDK Extension
+========================================
+
+.. automodule:: opentelemetry.sdk.extension.aws.trace.aws_xray_ids_generator
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format
+    :members:
+    :undoc-members:
+    :show-inheritance:

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py

@@ -12,6 +12,50 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Installation
+------------
+
+::
+
+    pip install opentelemetry-sdk-extension-aws
+
+AWS X-Ray IDs Generator
+-----------------------
+
+The **AWS X-Ray IDs Generator** provides a custom IDs Generator to make
+traces generated using the OpenTelemetry SDKs `TracerProvider` compatible
+with the AWS X-Ray backend service `trace ID format`_.
+
+Usage
+-----
+
+Configure the OTel SDK TracerProvider with the provided custom IDs Generator to
+make spans compatible with the AWS X-Ray backend tracing service.
+
+Install the OpenTelemetry SDK package.
+
+::
+
+    pip install opentelemetry-sdk
+
+Next, use the provided `AwsXRayIdsGenerator` to initialize the `TracerProvider`.
+
+.. code-block:: python
+
+    import opentelemetry.trace as trace
+    from opentelemetry.sdk.extension.aws.trace import AwsXRayIdsGenerator
+    from opentelemetry.sdk.trace import TracerProvider
+
+    trace.set_tracer_provider(
+        TracerProvider(ids_generator=AwsXRayIdsGenerator())
+    )
+
+API
+---
+.. _trace ID format: https://docs.aws.amazon.com/xray/latest/devguide/xray-api-sendingdata.html#xray-api-traceids
+"""
+
 import random
 import time
 

sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py

@@ -12,6 +12,42 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+AWS X-Ray Propagator
+--------------------
+
+The **AWS X-Ray Propagator** provides a propagator that when used, adds a `trace
+header`_ to outgoing traces that is compatible with the AWS X-Ray backend service.
+This allows the trace context to be propagated when a trace span multiple AWS
+services.
+
+Usage
+-----
+
+Use the provided AWS X-Ray Propagator to inject the necessary context into
+traces sent to external systems.
+
+This can be done by either setting this environment variable:
+
+::
+
+    export OTEL_PROPAGATORS = aws_xray
+
+
+Or by setting this propagator in your instrumented application:
+
+.. code-block:: python
+
+    from opentelemetry import propagators
+    from opentelemetry.sdk.extension.aws.trace.propagation.aws_xray_format import AwsXRayFormat
+
+    propagators.set_global_textmap(AwsXRayFormat())
+
+API
+---
+.. _trace header: https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader
+"""
+
 import logging
 import typing
 

tox.ini

@@ -140,6 +140,7 @@ envlist =
 
     lint
     docker-tests
+    docs
 
 [testenv]
 deps =
@@ -281,6 +282,17 @@ commands =
   test: pytest {posargs}
   coverage: {toxinidir}/scripts/coverage.sh
 
+[testenv:docs]
+deps =
+  -c {toxinidir}/dev-requirements.txt
+  -r {toxinidir}/docs-requirements.txt
+  pytest
+
+changedir = docs
+
+commands =
+  sphinx-build -E -a -W -b html -T . _build/html
+
 [testenv:lint]
 basepython: python3.8
 recreate = False