Add readTheDocs

.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: