Skip to content

Commit c9075cf

Browse files
NathanielRNaabmassalrex
authored
Add readTheDocs (open-telemetry#252)
Co-authored-by: Aaron Abbott <[email protected]> Co-authored-by: alrex <[email protected]>
1 parent f3a0782 commit c9075cf

File tree

40 files changed

+712
-2
lines changed

40 files changed

+712
-2
lines changed

Diff for: ‎.github/workflows/test.yml

+1-1
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ jobs:
8585
strategy:
8686
fail-fast: false
8787
matrix:
88-
tox-environment: [ "docker-tests", "lint" ]
88+
tox-environment: [ "docker-tests", "lint", "docs" ]
8989
name: ${{ matrix.tox-environment }}
9090
runs-on: ubuntu-latest
9191
steps:

Diff for: ‎.readthedocs.yml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Read the Docs configuration file
2+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
3+
version: 2
4+
5+
sphinx:
6+
configuration: docs/conf.py
7+
8+
build:
9+
image: latest
10+
11+
python:
12+
version: 3.9
13+
install:
14+
- requirements: docs-requirements.txt

Diff for: ‎docs-requirements.txt

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
sphinx~=2.4
2+
sphinx-rtd-theme~=0.4
3+
sphinx-autodoc-typehints~=1.10.2
4+
5+
# Need to install the api/sdk in the venv for autodoc. Modifying sys.path
6+
# doesn't work for pkg_resources.
7+
-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-api&subdirectory=opentelemetry-api"
8+
-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-sdk&subdirectory=opentelemetry-sdk"
9+
10+
# Required by opentelemetry-instrumentation
11+
fastapi~=0.58.1
12+
psutil~=5.7.0
13+
pymemcache~=1.3
14+
15+
-e "git+https://github.com/open-telemetry/opentelemetry-python.git#egg=opentelemetry-instrumentation&subdirectory=opentelemetry-instrumentation"
16+
17+
# Required by conf
18+
django>=2.2
19+
20+
# Required by instrumentation packages
21+
aiohttp~=3.0
22+
aiopg>=0.13.0
23+
asyncpg>=0.12.0
24+
boto~=2.0
25+
botocore~=1.0
26+
celery>=4.0
27+
flask~=1.0
28+
grpcio~=1.27
29+
mysql-connector-python~=8.0
30+
pymongo~=3.1
31+
PyMySQL~=0.9.3
32+
pyramid>=1.7
33+
redis>=2.6
34+
sqlalchemy>=1.0
35+
ddtrace>=0.34.0

Diff for: ‎docs/Makefile

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
SOURCEDIR = .
8+
BUILDDIR = _build
9+
10+
# Put it first so that "make" without argument is like "make help".
11+
help:
12+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
13+
14+
.PHONY: help Makefile
15+
16+
# Catch-all target: route all unknown targets to Sphinx using the new
17+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
18+
%: Makefile
19+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

Diff for: ‎docs/conf.py

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# http://www.sphinx-doc.org/en/master/config
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
13+
import os
14+
import sys
15+
from configparser import ConfigParser
16+
from os import listdir
17+
from os.path import isdir, join
18+
19+
# configure django to avoid the following exception:
20+
# django.core.exceptions.ImproperlyConfigured: Requested settings, but settings
21+
# are not configured. You must either define the environment variable
22+
# DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
23+
from django.conf import settings
24+
25+
settings.configure()
26+
27+
exp = "../exporter"
28+
exp_dirs = [
29+
os.path.abspath("/".join(["../exporter", f, "src"]))
30+
for f in listdir(exp)
31+
if isdir(join(exp, f))
32+
]
33+
34+
instr = "../instrumentation"
35+
instr_dirs = [
36+
os.path.abspath("/".join(["../instrumentation", f, "src"]))
37+
for f in listdir(instr)
38+
if isdir(join(instr, f))
39+
]
40+
41+
sdk_ext = "../sdk-extension"
42+
sdk_ext_dirs = [
43+
os.path.abspath("/".join(["../sdk-extension", f, "src"]))
44+
for f in listdir(sdk_ext)
45+
if isdir(join(sdk_ext, f))
46+
]
47+
48+
sys.path[:0] = exp_dirs + instr_dirs + sdk_ext_dirs
49+
50+
# -- Project information -----------------------------------------------------
51+
52+
project = "OpenTelemetry Python Contrib"
53+
copyright = "OpenTelemetry Authors" # pylint: disable=redefined-builtin
54+
author = "OpenTelemetry Authors"
55+
56+
57+
# -- General configuration ---------------------------------------------------
58+
59+
# Easy automatic cross-references for `code in backticks`
60+
default_role = "any"
61+
62+
# Add any Sphinx extension module names here, as strings. They can be
63+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
64+
# ones.
65+
extensions = [
66+
# API doc generation
67+
"sphinx.ext.autodoc",
68+
# Support for google-style docstrings
69+
"sphinx.ext.napoleon",
70+
# Infer types from hints instead of docstrings
71+
"sphinx_autodoc_typehints",
72+
# Add links to source from generated docs
73+
"sphinx.ext.viewcode",
74+
# Link to other sphinx docs
75+
"sphinx.ext.intersphinx",
76+
# Add a .nojekyll file to the generated HTML docs
77+
# https://help.github.com/en/articles/files-that-start-with-an-underscore-are-missing
78+
"sphinx.ext.githubpages",
79+
# Support external links to different versions in the Github repo
80+
"sphinx.ext.extlinks",
81+
]
82+
83+
intersphinx_mapping = {
84+
"python": ("https://docs.python.org/3/", None),
85+
"opentracing": (
86+
"https://opentracing-python.readthedocs.io/en/latest/",
87+
None,
88+
),
89+
"aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
90+
"wrapt": ("https://wrapt.readthedocs.io/en/latest/", None),
91+
"pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
92+
"opentelemetry": (
93+
"https://opentelemetry-python.readthedocs.io/en/latest/",
94+
None,
95+
),
96+
}
97+
98+
# http://www.sphinx-doc.org/en/master/config.html#confval-nitpicky
99+
# Sphinx will warn about all references where the target cannot be found.
100+
nitpicky = True
101+
# Sphinx does not recognize generic type TypeVars
102+
# Container supposedly were fixed, but does not work
103+
# https://github.com/sphinx-doc/sphinx/pull/3744
104+
nitpick_ignore = []
105+
106+
cfg = ConfigParser()
107+
cfg.read("./nitpick-exceptions.ini")
108+
mcfg = cfg["default"]
109+
110+
111+
def getlistcfg(strval):
112+
return [
113+
val.strip()
114+
for line in strval.split("\n")
115+
for val in line.split(",")
116+
if val.strip()
117+
]
118+
119+
120+
if "class_references" in mcfg:
121+
class_references = getlistcfg(mcfg["class_references"])
122+
for class_reference in class_references:
123+
nitpick_ignore.append(("py:class", class_reference,))
124+
125+
if "anys" in mcfg:
126+
anys = getlistcfg(mcfg["anys"])
127+
for any in anys:
128+
nitpick_ignore.append(("any", any,))
129+
130+
# Add any paths that contain templates here, relative to this directory.
131+
templates_path = ["_templates"]
132+
133+
# List of patterns, relative to source directory, that match files and
134+
# directories to ignore when looking for source files.
135+
# This pattern also affects html_static_path and html_extra_path.
136+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
137+
138+
autodoc_default_options = {
139+
"members": True,
140+
"undoc-members": True,
141+
"show-inheritance": True,
142+
"member-order": "bysource",
143+
}
144+
145+
# -- Options for HTML output -------------------------------------------------
146+
147+
# The theme to use for HTML and HTML Help pages. See the documentation for
148+
# a list of builtin themes.
149+
#
150+
html_theme = "sphinx_rtd_theme"
151+
152+
# Add any paths that contain custom static files (such as style sheets) here,
153+
# relative to this directory. They are copied after the builtin static files,
154+
# so a file named "default.css" will overwrite the builtin "default.css".
155+
html_static_path = []
156+
157+
# Support external links to specific versions of the files in the Github repo
158+
branch = os.environ.get("READTHEDOCS_VERSION")
159+
if branch is None or branch == "latest":
160+
branch = "master"
161+
162+
REPO = "open-telemetry/opentelemetry-python-contrib/"
163+
scm_raw_web = "https://raw.githubusercontent.com/" + REPO + branch
164+
scm_web = "https://github.com/" + REPO + "blob/" + branch
165+
166+
# Store variables in the epilogue so they are globally available.
167+
rst_epilog = """
168+
.. |SCM_WEB| replace:: {s}
169+
.. |SCM_RAW_WEB| replace:: {sr}
170+
.. |SCM_BRANCH| replace:: {b}
171+
""".format(
172+
s=scm_web, sr=scm_raw_web, b=branch
173+
)
174+
175+
# used to have links to repo files
176+
extlinks = {
177+
"scm_raw_web": (scm_raw_web + "/%s", "scm_raw_web"),
178+
"scm_web": (scm_web + "/%s", "scm_web"),
179+
}

Diff for: ‎docs/exporter/datadog/datadog.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
OpenTelemetry Datadog Exporter
2+
==============================
3+
4+
.. automodule:: opentelemetry.exporter.datadog
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

Diff for: ‎docs/index.rst

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
OpenTelemetry-Python-Contrib
2+
============================
3+
4+
Complimentary instrumentation and vendor-specific packages for use with the
5+
Python `OpenTelemetry <https://opentelemetry.io/>`_ client.
6+
7+
.. image:: https://img.shields.io/gitter/room/opentelemetry/opentelemetry-python
8+
:target: https://gitter.im/open-telemetry/opentelemetry-python
9+
:alt: Gitter Chat
10+
11+
12+
**Please note** that this library is currently in _beta_, and shouldn't
13+
generally be used in production environments.
14+
15+
Installation
16+
------------
17+
18+
There are several complimentary packages available on PyPI which can be
19+
installed separately via pip:
20+
21+
.. code-block:: sh
22+
23+
pip install opentelemetry-exporter-{exporter}
24+
pip install opentelemetry-instrumentation-{instrumentation}
25+
pip install opentelemetry-sdk-extension-{sdkextension}
26+
27+
A complete list of packages can be found at the
28+
`Contrib repo instrumentation <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/instrumentation>`_
29+
and `Contrib repo exporter <https://github.com/open-telemetry/opentelemetry-python-contrib/tree/master/exporter>`_ directories.
30+
31+
Extensions
32+
----------
33+
34+
Visit `OpenTelemetry Registry <https://opentelemetry.io/registry/?s=python>`_ to
35+
find a lit of related projects like exporters, instrumentation libraries, tracer
36+
implementations, etc.
37+
38+
Installing Cutting Edge Packages
39+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
40+
41+
While the project is pre-1.0, there may be significant functionality that
42+
has not yet been released to PyPI. In that situation, you may want to
43+
install the packages directly from the repo. This can be done by cloning the
44+
repository and doing an `editable
45+
install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_:
46+
47+
.. code-block:: sh
48+
49+
git clone https://github.com/open-telemetry/opentelemetry-python-contrib.git
50+
cd opentelemetry-python-contrib
51+
pip install -e ./instrumentation/opentelemetry-instrumentation-flask
52+
pip install -e ./instrumentation/opentelemetry-instrumentation-botocore
53+
pip install -e ./sdk-extension/opentelemetry-sdk-extension-aws
54+
55+
56+
.. toctree::
57+
:maxdepth: 2
58+
:caption: OpenTelemetry Exporters
59+
:name: exporters
60+
:glob:
61+
62+
exporter/**
63+
64+
.. toctree::
65+
:maxdepth: 2
66+
:caption: OpenTelemetry Instrumentations
67+
:name: Instrumentations
68+
:glob:
69+
70+
instrumentation/**
71+
72+
.. toctree::
73+
:maxdepth: 2
74+
:caption: OpenTelemetry Performance
75+
:name: Performance
76+
:glob:
77+
78+
performance/**
79+
80+
.. toctree::
81+
:maxdepth: 2
82+
:caption: OpenTelemetry SDK Extensions
83+
:name: SDK Extensions
84+
:glob:
85+
86+
sdk-extension/**
87+
88+
Indices and tables
89+
------------------
90+
91+
* :ref:`genindex`
92+
* :ref:`modindex`
93+
* :ref:`search`

Diff for: ‎docs/instrumentation/aiohttp_client/aiohttp_client.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
OpenTelemetry aiohttp client Instrumentation
2+
============================================
3+
4+
.. automodule:: opentelemetry.instrumentation.aiohttp_client
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

Diff for: ‎docs/instrumentation/aiopg/aiopg.rst

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
OpenTelemetry aiopg Instrumentation
2+
===================================
3+
4+
.. automodule:: opentelemetry.instrumentation.aiopg
5+
:members:
6+
:undoc-members:
7+
:show-inheritance:

Diff for: ‎docs/instrumentation/asgi/asgi.rst

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. include:: ../../../instrumentation/opentelemetry-instrumentation-asgi/README.rst
2+
3+
API
4+
---
5+
6+
.. automodule:: opentelemetry.instrumentation.asgi
7+
:members:
8+
:undoc-members:
9+
:show-inheritance:

Diff for: ‎docs/instrumentation/asyncpg/asyncpg.rst

+10
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
OpenTelemetry asyncpg Instrumentation
2+
=====================================
3+
4+
Module contents
5+
---------------
6+
7+
.. automodule:: opentelemetry.instrumentation.asyncpg
8+
:members:
9+
:undoc-members:
10+
:show-inheritance:

0 commit comments

Comments
 (0)