diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index d5f6c2af5..06e960a9c 100644
--- a/.github/workflows/test.yml
+++ b/.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:
diff --git a/.readthedocs.yml b/.readthedocs.yml
new file mode 100644
index 000000000..474f366d1
--- /dev/null
+++ b/.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
diff --git a/docs-requirements.txt b/docs-requirements.txt
new file mode 100644
index 000000000..dc1cbc779
--- /dev/null
+++ b/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
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 000000000..51285967a
--- /dev/null
+++ b/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)
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 000000000..e0dbffaeb
--- /dev/null
+++ b/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"),
+}
diff --git a/docs/exporter/datadog/datadog.rst b/docs/exporter/datadog/datadog.rst
new file mode 100644
index 000000000..3b43c2bdf
--- /dev/null
+++ b/docs/exporter/datadog/datadog.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Datadog Exporter
+==============================
+
+.. automodule:: opentelemetry.exporter.datadog
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 000000000..683d1c639
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,93 @@
+OpenTelemetry-Python-Contrib
+============================
+
+Complimentary instrumentation and vendor-specific packages for use with the
+Python `OpenTelemetry `_ 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 `_
+and `Contrib repo exporter `_ directories.
+
+Extensions
+----------
+
+Visit `OpenTelemetry Registry `_ 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 `_:
+
+.. 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`
diff --git a/docs/instrumentation/aiohttp_client/aiohttp_client.rst b/docs/instrumentation/aiohttp_client/aiohttp_client.rst
new file mode 100644
index 000000000..f8549f07f
--- /dev/null
+++ b/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:
diff --git a/docs/instrumentation/aiopg/aiopg.rst b/docs/instrumentation/aiopg/aiopg.rst
new file mode 100644
index 000000000..9da450c4e
--- /dev/null
+++ b/docs/instrumentation/aiopg/aiopg.rst
@@ -0,0 +1,7 @@
+OpenTelemetry aiopg Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.aiopg
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/asgi/asgi.rst b/docs/instrumentation/asgi/asgi.rst
new file mode 100644
index 000000000..b988e4de4
--- /dev/null
+++ b/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:
diff --git a/docs/instrumentation/asyncpg/asyncpg.rst b/docs/instrumentation/asyncpg/asyncpg.rst
new file mode 100644
index 000000000..d4ee9b4ab
--- /dev/null
+++ b/docs/instrumentation/asyncpg/asyncpg.rst
@@ -0,0 +1,10 @@
+OpenTelemetry asyncpg Instrumentation
+=====================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.instrumentation.asyncpg
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/boto/boto.rst b/docs/instrumentation/boto/boto.rst
new file mode 100644
index 000000000..c438c2466
--- /dev/null
+++ b/docs/instrumentation/boto/boto.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Boto Instrumentation
+==================================
+
+.. automodule:: opentelemetry.instrumentation.boto
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/botocore/botocore.rst b/docs/instrumentation/botocore/botocore.rst
new file mode 100644
index 000000000..eb8ea6bcf
--- /dev/null
+++ b/docs/instrumentation/botocore/botocore.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Botocore Instrumentation
+======================================
+
+.. automodule:: opentelemetry.instrumentation.botocore
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/celery/celery.rst b/docs/instrumentation/celery/celery.rst
new file mode 100644
index 000000000..c85f3adb5
--- /dev/null
+++ b/docs/instrumentation/celery/celery.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Celery Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.celery
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/dbapi/dbapi.rst b/docs/instrumentation/dbapi/dbapi.rst
new file mode 100644
index 000000000..a20be6309
--- /dev/null
+++ b/docs/instrumentation/dbapi/dbapi.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Database API Instrumentation
+==========================================
+
+.. automodule:: opentelemetry.instrumentation.dbapi
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/django/django.rst b/docs/instrumentation/django/django.rst
new file mode 100644
index 000000000..807673084
--- /dev/null
+++ b/docs/instrumentation/django/django.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Django Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.django
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/fastapi/fastapi.rst b/docs/instrumentation/fastapi/fastapi.rst
new file mode 100644
index 000000000..09eb8a828
--- /dev/null
+++ b/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:
\ No newline at end of file
diff --git a/docs/instrumentation/flask/flask.rst b/docs/instrumentation/flask/flask.rst
new file mode 100644
index 000000000..ac8932acd
--- /dev/null
+++ b/docs/instrumentation/flask/flask.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Flask Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.flask
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/grpc/grpc.rst b/docs/instrumentation/grpc/grpc.rst
new file mode 100644
index 000000000..243f69614
--- /dev/null
+++ b/docs/instrumentation/grpc/grpc.rst
@@ -0,0 +1,10 @@
+OpenTelemetry gRPC Instrumentation
+==================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.instrumentation.grpc
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/jinja2/jinja2.rst b/docs/instrumentation/jinja2/jinja2.rst
new file mode 100644
index 000000000..5c7143724
--- /dev/null
+++ b/docs/instrumentation/jinja2/jinja2.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Jinja2 Instrumentation
+====================================
+
+.. automodule:: opentelemetry.instrumentation.jinja2
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/mysql/mysql.rst b/docs/instrumentation/mysql/mysql.rst
new file mode 100644
index 000000000..3a4a41542
--- /dev/null
+++ b/docs/instrumentation/mysql/mysql.rst
@@ -0,0 +1,7 @@
+OpenTelemetry MySQL Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.mysql
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/psycopg2/psycopg2.rst b/docs/instrumentation/psycopg2/psycopg2.rst
new file mode 100644
index 000000000..69be31b2d
--- /dev/null
+++ b/docs/instrumentation/psycopg2/psycopg2.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Psycopg Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.psycopg2
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/pymemcache/pymemcache.rst b/docs/instrumentation/pymemcache/pymemcache.rst
new file mode 100644
index 000000000..2a77b829d
--- /dev/null
+++ b/docs/instrumentation/pymemcache/pymemcache.rst
@@ -0,0 +1,7 @@
+OpenTelemetry pymemcache Instrumentation
+========================================
+
+.. automodule:: opentelemetry.instrumentation.pymemcache
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/pymongo/pymongo.rst b/docs/instrumentation/pymongo/pymongo.rst
new file mode 100644
index 000000000..4eb68be27
--- /dev/null
+++ b/docs/instrumentation/pymongo/pymongo.rst
@@ -0,0 +1,7 @@
+OpenTelemetry pymongo Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pymongo
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/pymysql/pymysql.rst b/docs/instrumentation/pymysql/pymysql.rst
new file mode 100644
index 000000000..26482292f
--- /dev/null
+++ b/docs/instrumentation/pymysql/pymysql.rst
@@ -0,0 +1,7 @@
+OpenTelemetry PyMySQL Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pymysql
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/pyramid/pyramid.rst b/docs/instrumentation/pyramid/pyramid.rst
new file mode 100644
index 000000000..56abd2800
--- /dev/null
+++ b/docs/instrumentation/pyramid/pyramid.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Pyramid Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.pyramid
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/redis/redis.rst b/docs/instrumentation/redis/redis.rst
new file mode 100644
index 000000000..4e21bce24
--- /dev/null
+++ b/docs/instrumentation/redis/redis.rst
@@ -0,0 +1,7 @@
+OpenTelemetry Redis Instrumentation
+===================================
+
+.. automodule:: opentelemetry.instrumentation.redis
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/requests/requests.rst b/docs/instrumentation/requests/requests.rst
new file mode 100644
index 000000000..7a0665cd9
--- /dev/null
+++ b/docs/instrumentation/requests/requests.rst
@@ -0,0 +1,7 @@
+OpenTelemetry requests Instrumentation
+======================================
+
+.. automodule:: opentelemetry.instrumentation.requests
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/sqlalchemy/sqlalchemy.rst b/docs/instrumentation/sqlalchemy/sqlalchemy.rst
new file mode 100644
index 000000000..1a1895ea6
--- /dev/null
+++ b/docs/instrumentation/sqlalchemy/sqlalchemy.rst
@@ -0,0 +1,7 @@
+OpenTelemetry SQLAlchemy Instrumentation
+========================================
+
+.. automodule:: opentelemetry.instrumentation.sqlalchemy
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/sqlite3/sqlite3.rst b/docs/instrumentation/sqlite3/sqlite3.rst
new file mode 100644
index 000000000..36b541ccd
--- /dev/null
+++ b/docs/instrumentation/sqlite3/sqlite3.rst
@@ -0,0 +1,7 @@
+OpenTelemetry SQLite3 Instrumentation
+=====================================
+
+.. automodule:: opentelemetry.instrumentation.sqlite3
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/instrumentation/starlette/starlette.rst b/docs/instrumentation/starlette/starlette.rst
new file mode 100644
index 000000000..0efa8cce8
--- /dev/null
+++ b/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:
\ No newline at end of file
diff --git a/docs/instrumentation/system_metrics/system_metrics.rst b/docs/instrumentation/system_metrics/system_metrics.rst
new file mode 100644
index 000000000..96b39d926
--- /dev/null
+++ b/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:
diff --git a/docs/instrumentation/wsgi/wsgi.rst b/docs/instrumentation/wsgi/wsgi.rst
new file mode 100644
index 000000000..39ad5ffd5
--- /dev/null
+++ b/docs/instrumentation/wsgi/wsgi.rst
@@ -0,0 +1,7 @@
+OpenTelemetry WSGI Instrumentation
+==================================
+
+.. automodule:: opentelemetry.instrumentation.wsgi
+ :members:
+ :undoc-members:
+ :show-inheritance:
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 000000000..27f573b87
--- /dev/null
+++ b/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
diff --git a/docs/nitpick-exceptions.ini b/docs/nitpick-exceptions.ini
new file mode 100644
index 000000000..3143b9cd7
--- /dev/null
+++ b/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.*
diff --git a/docs/performance/benchmarks.rst b/docs/performance/benchmarks.rst
index 428d5acbb..99859a27d 100644
--- a/docs/performance/benchmarks.rst
+++ b/docs/performance/benchmarks.rst
@@ -1,4 +1,4 @@
Performance Tests - Benchmarks
==============================
-Click `here _` to view the latest performance benchmarks for packages in this repo.
+Click `here `_ to view the latest performance benchmarks for packages in this repo.
diff --git a/docs/sdk-extension/aws/aws.rst b/docs/sdk-extension/aws/aws.rst
new file mode 100644
index 000000000..1306e4566
--- /dev/null
+++ b/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:
diff --git a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py
index 6928e0b18..bf908e03f 100644
--- a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/aws_xray_ids_generator.py
+++ b/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
diff --git a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py b/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py
index 54b98e0ba..63ccb0020 100644
--- a/sdk-extension/opentelemetry-sdk-extension-aws/src/opentelemetry/sdk/extension/aws/trace/propagation/aws_xray_format.py
+++ b/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
diff --git a/tox.ini b/tox.ini
index e4958aa7f..87462e4c8 100644
--- a/tox.ini
+++ b/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