Skip to content

Commit

Permalink
Add docs build to Contrib repo
Browse files Browse the repository at this point in the history
  • Loading branch information
NathanielRN committed Dec 12, 2020
1 parent 6ccc2f4 commit 5f4cdd4
Show file tree
Hide file tree
Showing 38 changed files with 685 additions and 1 deletion.
2 changes: 1 addition & 1 deletion .github/workflows/test.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
35 changes: 35 additions & 0 deletions docs-requirements.txt
Original file line number Diff line number Diff line change
@@ -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
19 changes: 19 additions & 0 deletions docs/Makefile
Original file line number Diff line number Diff line change
@@ -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)
175 changes: 175 additions & 0 deletions docs/conf.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,175 @@
# 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),
}

# 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"),
}
7 changes: 7 additions & 0 deletions docs/exporter/datadog/datadog.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry Datadog Exporter
==============================

.. automodule:: opentelemetry.exporter.datadog
:members:
:undoc-members:
:show-inheritance:
85 changes: 85 additions & 0 deletions docs/index.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
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 SDK Extensions
:name: SDK Extensions
:glob:

sdk-extension/**

Indices and tables
------------------

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
7 changes: 7 additions & 0 deletions docs/instrumentation/aiohttp_client/aiohttp_client.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry aiohttp client Instrumentation
============================================

.. automodule:: opentelemetry.instrumentation.aiohttp_client
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/instrumentation/aiopg/aiopg.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry aiopg Instrumentation
===================================

.. automodule:: opentelemetry.instrumentation.aiopg
:members:
:undoc-members:
:show-inheritance:
9 changes: 9 additions & 0 deletions docs/instrumentation/asgi/asgi.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
.. include:: ../../../instrumentation/opentelemetry-instrumentation-asgi/README.rst

API
---

.. automodule:: opentelemetry.instrumentation.asgi
:members:
:undoc-members:
:show-inheritance:
10 changes: 10 additions & 0 deletions docs/instrumentation/asyncpg/asyncpg.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
Opentelemetry asyncpg Instrumentation
=====================================

Module contents
---------------

.. automodule:: opentelemetry.instrumentation.asyncpg
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/instrumentation/boto/boto.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry Boto Instrumentation
==================================

.. automodule:: opentelemetry.instrumentation.boto
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/instrumentation/botocore/botocore.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry Botocore Instrumentation
======================================

.. automodule:: opentelemetry.instrumentation.botocore
:members:
:undoc-members:
:show-inheritance:
7 changes: 7 additions & 0 deletions docs/instrumentation/celery/celery.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
OpenTelemetry Celery Instrumentation
====================================

.. automodule:: opentelemetry.instrumentation.celery
:members:
:undoc-members:
:show-inheritance:
Loading

0 comments on commit 5f4cdd4

Please sign in to comment.