Repository: open-telemetry/opentelemetry-python-contrib

Issue:
Add read the docs build to Contrib repo
We updated all the links to the point to what _would_ be the right links in this PR https://github.com/open-telemetry/opentelemetry-python-contrib/pull/176

A follow up is to add a `readTheDocs` build here just like we have on the Core repo so that these links work.


Discussion:

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
--- /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/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
--- 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
--- 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
 


Test patch:
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
--- 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: