Improve docs structure (#467)

- Creates a tree structure for documentation, it allows to organize it better from a developer point of view and also the rendered documentation should be easier to navigate. - Moves partially the main readme to be included in the online docs, the main readme will be updated to have a link to avoid duplicated content) - Moves the examples folder to the docs, so they can be accessed through the online documentation. Creates a new pair of "macros" to create links to specific versions, scm_web & scm_raw_web. Co-authored-by: Chris Kleinknecht <[email protected]>
open-telemetry · Mar 10, 2020 · d5f3a7f · d5f3a7f
1 parent 9850fb3
commit d5f3a7f
Show file tree

Hide file tree

Showing 79 changed files with 560 additions and 372 deletions.
diff --git a/docs-requirements.txt b/docs-requirements.txt
@@ -8,3 +8,6 @@ Deprecated>=1.2.6
 thrift>=0.10.0
 pymongo~=3.1
 flask~=1.0
+mysql-connector-python ~=  8.0
+wrapt >= 1.0.0, < 2.0.0
+psycopg2-binary >= 2.7.3.1
diff --git a/docs/api/api.rst b/docs/api/api.rst
@@ -0,0 +1,12 @@
+OpenTelemetry Python API
+========================
+
+.. TODO: what is the API
+
+.. toctree::
+    :maxdepth: 1
+
+    context
+    metrics
+    trace
+    util.loader
diff --git a/docs/opentelemetry.context.context.rst → docs/api/context.context.rst b/docs/opentelemetry.context.context.rst → docs/api/context.context.rst
diff --git a/docs/opentelemetry.context.rst → docs/api/context.rst b/docs/opentelemetry.context.rst → docs/api/context.rst
@@ -6,7 +6,7 @@ Submodules
 
 .. toctree::
 
-   opentelemetry.context.context
+   context.context
 
 Module contents
 ---------------

diff --git a/docs/opentelemetry.metrics.rst → docs/api/metrics.rst b/docs/opentelemetry.metrics.rst → docs/api/metrics.rst
diff --git a/docs/opentelemetry.trace.rst → docs/api/trace.rst b/docs/opentelemetry.trace.rst → docs/api/trace.rst
@@ -6,8 +6,8 @@ Submodules
 
 .. toctree::
 
-   opentelemetry.trace.sampling
-   opentelemetry.trace.status
+   trace.sampling
+   trace.status
 
 Module contents
 ---------------

diff --git a/docs/opentelemetry.trace.sampling.rst → docs/api/trace.sampling.rst b/docs/opentelemetry.trace.sampling.rst → docs/api/trace.sampling.rst
diff --git a/docs/opentelemetry.trace.status.rst → docs/api/trace.status.rst b/docs/opentelemetry.trace.status.rst → docs/api/trace.status.rst
diff --git a/docs/opentelemetry.util.loader.rst → docs/api/util.loader.rst b/docs/opentelemetry.util.loader.rst → docs/api/util.loader.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -30,8 +30,8 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "OpenTelemetry"
-copyright = "2019, OpenTelemetry Authors"  # pylint: disable=redefined-builtin
+project = "OpenTelemetry Python"
+copyright = "OpenTelemetry Authors"  # pylint: disable=redefined-builtin
 author = "OpenTelemetry Authors"
 
 
@@ -57,6 +57,8 @@
     # 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 = {
@@ -106,3 +108,27 @@
 # 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/"
+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/examples/basic_tracer/README.rst b/docs/examples/basic_tracer/README.rst
@@ -0,0 +1,76 @@
+Basic Tracer
+============
+
+This example shows how to use OpenTelemetry to instrument a Python application - e.g. a batch job.
+It supports exporting spans either to the console or to Jaeger_.
+
+The source files required to run this example are available :scm_web:`here <docs/examples/basic_tracer/>`.
+
+
+Run the application
+-------------------
+
+Console
+*******
+
+* Run the sample
+
+.. code-block:: sh
+
+    $ python tracer.py
+
+The output will be displayed at the console
+
+::
+
+    Hello world from OpenTelemetry Python!
+    Span(name="baz", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x5611c1407e06e4d7, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={})), start_time=2019-11-07T21:26:45.934412Z, end_time=2019-11-07T21:26:45.934567Z)
+    Span(name="bar", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1b9db0e0cc1a3f60, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={})), start_time=2019-11-07T21:26:45.934396Z, end_time=2019-11-07T21:26:45.934576Z)
+    Span(name="foo", context=SpanContext(trace_id=0xf906f80f64d57c71ea8da4dfbbd2ddf2, span_id=0x1d5d87441ec2f410, trace_state={}), kind=SpanKind.INTERNAL, parent=None, start_time=2019-11-07T21:26:45.934369Z, end_time=2019-11-07T21:26:45.934580Z)
+
+
+Jaeger
+******
+
+Setup `Jaeger Tracing <https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one>`_.
+
+* Run the sample
+
+.. code-block:: sh
+
+    $ pip install opentelemetry-ext-jaeger
+    $ EXPORTER=jaeger python tracer.py
+
+
+The traces should be available in the Jaeger UI at `<http://localhost:16686>`_
+
+
+Collector
+*********
+
+* Start Collector
+
+.. code-block:: sh
+
+    $ pip install docker-compose
+    $ cd docker
+    $ docker-compose up
+
+* Run the sample
+
+.. code-block:: sh
+
+    $ pip install opentelemetry-ext-otcollector
+    $ EXPORTER=collector python tracer.py
+
+
+Collector is configured to export to Jaeger, follow Jaeger UI instructions to find the traces.
+
+Useful links
+------------
+
+- For more information on OpenTelemetry, visit OpenTelemetry_.
+- For more information on tracing in Python, visit Jaeger_.
+
+.. _Jaeger: https://www.jaegertracing.io/
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
diff --git a/examples/basic_tracer/__init__.py → docs/examples/basic_tracer/__init__.py b/examples/basic_tracer/__init__.py → docs/examples/basic_tracer/__init__.py
diff --git a/...basic_tracer/docker/collector-config.yaml → ...basic_tracer/docker/collector-config.yaml b/...basic_tracer/docker/collector-config.yaml → ...basic_tracer/docker/collector-config.yaml
diff --git a/...s/basic_tracer/docker/docker-compose.yaml → ...s/basic_tracer/docker/docker-compose.yaml b/...s/basic_tracer/docker/docker-compose.yaml → ...s/basic_tracer/docker/docker-compose.yaml
diff --git a/examples/basic_tracer/tests/__init__.py → docs/examples/basic_tracer/tests/__init__.py b/examples/basic_tracer/tests/__init__.py → docs/examples/basic_tracer/tests/__init__.py
diff --git a/examples/basic_tracer/tests/test_tracer.py → ...xamples/basic_tracer/tests/test_tracer.py b/examples/basic_tracer/tests/test_tracer.py → ...xamples/basic_tracer/tests/test_tracer.py
diff --git a/examples/basic_tracer/tracer.py → docs/examples/basic_tracer/tracer.py b/examples/basic_tracer/tracer.py → docs/examples/basic_tracer/tracer.py
diff --git a/docs/examples/http/README.rst b/docs/examples/http/README.rst
@@ -0,0 +1,87 @@
+HTTP Example
+============
+
+This example shows how to use
+`OpenTelemetryMiddleware <https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-wsgi>`_
+and `requests <https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-http-requests>`_ integrations to instrument a client and a server in Python.
+It supports exporting spans either to the console or to Jaeger_.
+
+The source files required to run this example are available :scm_web:`here <docs/examples/http/>`.
+
+
+Installation
+------------
+
+.. code-block:: sh
+
+    $ pip install opentelemetry-api
+    $ pip install opentelemetry-sdk
+    $ pip install opentelemetry-ext-wsgi
+    $ pip install opentelemetry-ext-http-requests
+
+
+Run the application
+-------------------
+
+Console
+*******
+
+* Run the server
+
+.. code-block:: sh
+
+    $ python server.py
+
+
+* Run the client from a different terminal
+
+.. code-block:: sh
+
+    $ python tracer_client.py
+
+
+The output will be displayed at the console on the client side
+
+::
+
+    Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), kind=SpanKind.CLIENT, parent=None, start_time=2019-11-07T21:52:59.591634Z, end_time=2019-11-07T21:53:00.386014Z)
+
+
+And on the server
+
+::
+
+    127.0.0.1 - - [07/Nov/2019 13:53:00] "GET / HTTP/1.1" 200 -
+    Span(name="/wiki/Rabbit", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x4bf0be462b91d6ef, trace_state={}), kind=SpanKind.CLIENT, parent=Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={})), start_time=2019-11-07T21:52:59.601597Z, end_time=2019-11-07T21:53:00.380491Z)
+    Span(name="parent", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x68338643ccb2d53b, trace_state={}), kind=SpanKind.INTERNAL, parent=Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={})), start_time=2019-11-07T21:52:59.601233Z, end_time=2019-11-07T21:53:00.384485Z)
+    Span(name="/", context=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x36050ac596949bc1, trace_state={}), kind=SpanKind.SERVER, parent=SpanContext(trace_id=0x7c5c0d62031570f00fd106d968139300, span_id=0x3703fd889dcdeb2b, trace_state={}), start_time=2019-11-07T21:52:59.600816Z, end_time=2019-11-07T21:53:00.385322Z)
+
+
+Jaeger
+******
+
+Setup `Jaeger Tracing <https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one>`_.
+
+* Run the server
+
+.. code-block:: sh
+
+    $ pip install opentelemetry-ext-jaeger
+    $ EXPORTER=jaeger python server.py
+
+* Run the client from a different terminal
+
+.. code-block:: sh
+
+    $ EXPORTER=jaeger python tracer_client.py
+
+The traces should be available in the Jaeger UI at `<http://localhost:16686>`_
+
+Useful links
+------------
+
+- For more information on OpenTelemetry, visit OpenTelemetry_.
+- For more information on tracing in Python, visit Jaeger_.
+
+.. _Jaeger: https://www.jaegertracing.io/
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
diff --git a/examples/http/__init__.py → docs/examples/http/__init__.py b/examples/http/__init__.py → docs/examples/http/__init__.py
diff --git a/examples/http/requirements.txt → docs/examples/http/requirements.txt b/examples/http/requirements.txt → docs/examples/http/requirements.txt
diff --git a/examples/http/server.py → docs/examples/http/server.py b/examples/http/server.py → docs/examples/http/server.py
diff --git a/examples/http/tests/__init__.py → docs/examples/http/tests/__init__.py b/examples/http/tests/__init__.py → docs/examples/http/tests/__init__.py
diff --git a/examples/http/tests/test_http.py → docs/examples/http/tests/test_http.py b/examples/http/tests/test_http.py → docs/examples/http/tests/test_http.py
diff --git a/examples/http/tracer_client.py → docs/examples/http/tracer_client.py b/examples/http/tracer_client.py → docs/examples/http/tracer_client.py
diff --git a/examples/metrics/observer_example.py → docs/examples/metrics/observer_example.py b/examples/metrics/observer_example.py → docs/examples/metrics/observer_example.py
diff --git a/examples/metrics/prometheus.py → docs/examples/metrics/prometheus.py b/examples/metrics/prometheus.py → docs/examples/metrics/prometheus.py
diff --git a/examples/metrics/record.py → docs/examples/metrics/record.py b/examples/metrics/record.py → docs/examples/metrics/record.py
diff --git a/examples/metrics/simple_example.py → docs/examples/metrics/simple_example.py b/examples/metrics/simple_example.py → docs/examples/metrics/simple_example.py
diff --git a/...ples/opentelemetry-example-app/README.rst → ...ples/opentelemetry-example-app/README.rst b/...ples/opentelemetry-example-app/README.rst → ...ples/opentelemetry-example-app/README.rst
diff --git a/examples/opentelemetry-example-app/setup.py → ...amples/opentelemetry-example-app/setup.py b/examples/opentelemetry-example-app/setup.py → ...amples/opentelemetry-example-app/setup.py
diff --git a/...src/opentelemetry_example_app/__init__.py → ...src/opentelemetry_example_app/__init__.py b/...src/opentelemetry_example_app/__init__.py → ...src/opentelemetry_example_app/__init__.py
diff --git a/...pentelemetry_example_app/flask_example.py → ...pentelemetry_example_app/flask_example.py b/...pentelemetry_example_app/flask_example.py → ...pentelemetry_example_app/flask_example.py
diff --git a/...entelemetry-example-app/tests/__init__.py → ...entelemetry-example-app/tests/__init__.py b/...entelemetry-example-app/tests/__init__.py → ...entelemetry-example-app/tests/__init__.py
diff --git a/...y-example-app/tests/test_flask_example.py → ...y-example-app/tests/test_flask_example.py b/...y-example-app/tests/test_flask_example.py → ...y-example-app/tests/test_flask_example.py
diff --git a/docs/examples/opentracing/README.rst b/docs/examples/opentracing/README.rst
@@ -0,0 +1,97 @@
+OpenTracing Shim Example
+==========================
+
+This example shows how to use the `opentelemetry-ext-opentracing-shim
+package <https://github.com/open-telemetry/opentelemetry-python/tree/master/ext/opentelemetry-ext-opentracing-shim>`_
+to interact with libraries instrumented with
+`opentracing-python <https://github.com/opentracing/opentracing-python>`_.
+
+The included ``rediscache`` library creates spans via the OpenTracing Redis
+integration,
+`redis_opentracing <https://github.com/opentracing-contrib/python-redis>`_.
+Spans are exported via the Jaeger exporter, which is attached to the
+OpenTelemetry tracer.
+
+
+The source files required to run this example are available :scm_web:`here <docs/examples/opentracing/>`.
+
+Installation
+------------
+
+Jaeger
+******
+
+Setup `Jaeger Tracing <https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one>`_.
+
+Redis
+*****
+
+Install Redis following the `instructions <https://redis.io/topics/quickstart>`_.
+
+Make sure that the Redis server is running by executing this:
+
+.. code-block:: sh
+
+    $ redis-server
+
+
+Python Dependencies
+*******************
+
+Install the Python dependencies in :scm_raw_web:`requirements.txt <docs/examples/opentracing>`
+
+.. code-block:: sh
+
+  $ pip install -r requirements.txt
+
+
+Alternatively, you can install the Python dependencies separately:
+
+.. code-block:: sh
+
+  $ pip install \
+    opentelemetry-api \
+    opentelemetry-sdk \
+    opentelemetry-ext-jaeger \
+    opentelemetry-opentracing-shim \
+    redis \
+    redis_opentracing
+
+
+Run the Application
+-------------------
+
+The example script calculates a few Fibonacci numbers and stores the results in
+Redis. The script, the ``rediscache`` library, and the OpenTracing Redis
+integration all contribute spans to the trace.
+
+To run the script:
+
+.. code-block:: sh
+
+  $ python main.py
+
+
+After running, you can view the generated trace in the Jaeger UI.
+
+Jaeger UI
+*********
+
+Open the Jaeger UI in your browser at
+`<http://localhost:16686>`_ and view traces for the
+"OpenTracing Shim Example" service.
+
+Each ``main.py`` run should generate a trace, and each trace should include
+multiple spans that represent calls to Redis.
+
+Note that tags and logs (OpenTracing) and attributes and events (OpenTelemetry)
+from both tracing systems appear in the exported trace.
+
+Useful links
+------------
+
+- For more information on OpenTelemetry, visit OpenTelemetry_.
+- For more information on tracing in Python, visit Jaeger_.
+
+.. _Jaeger: https://www.jaegertracing.io/
+.. _OpenTelemetry: https://github.com/open-telemetry/opentelemetry-python/
diff --git a/examples/opentracing/__init__.py → docs/examples/opentracing/__init__.py b/examples/opentracing/__init__.py → docs/examples/opentracing/__init__.py
diff --git a/...entracing/images/jaeger-span-expanded.png → ...entracing/images/jaeger-span-expanded.png b/...entracing/images/jaeger-span-expanded.png → ...entracing/images/jaeger-span-expanded.png
diff --git a/.../opentracing/images/jaeger-trace-full.png → .../opentracing/images/jaeger-trace-full.png b/.../opentracing/images/jaeger-trace-full.png → .../opentracing/images/jaeger-trace-full.png
diff --git a/examples/opentracing/main.py → docs/examples/opentracing/main.py b/examples/opentracing/main.py → docs/examples/opentracing/main.py
diff --git a/examples/opentracing/rediscache.py → docs/examples/opentracing/rediscache.py b/examples/opentracing/rediscache.py → docs/examples/opentracing/rediscache.py
diff --git a/examples/opentracing/requirements.txt → docs/examples/opentracing/requirements.txt b/examples/opentracing/requirements.txt → docs/examples/opentracing/requirements.txt
diff --git a/docs/ext/dbapi/dbapi.rst b/docs/ext/dbapi/dbapi.rst
@@ -0,0 +1,10 @@
+.. include:: ../../../ext/opentelemetry-ext-dbapi/README.rst
+
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.dbapi
+    :members:
+    :undoc-members:
+    :show-inheritance:
diff --git a/docs/opentelemetry.ext.flask.rst → docs/ext/flask/flask.rst b/docs/opentelemetry.ext.flask.rst → docs/ext/flask/flask.rst
@@ -1,5 +1,5 @@
-opentelemetry.ext.flask package
-==========================================
+.. include:: ../../../ext/opentelemetry-ext-flask/README.rst
+
 
 Module contents
 ---------------

diff --git a/docs/opentelemetry.ext.http_requests.rst → docs/ext/http_requests/http_requests.rst b/docs/opentelemetry.ext.http_requests.rst → docs/ext/http_requests/http_requests.rst
@@ -1,5 +1,4 @@
-opentelemetry.ext.http_requests package
-==========================================
+.. include:: ../../../ext/opentelemetry-ext-http-requests/README.rst
 
 Module contents
 ---------------

diff --git a/docs/ext/jaeger/jaeger.rst b/docs/ext/jaeger/jaeger.rst
@@ -0,0 +1,17 @@
+.. include:: ../../../ext/opentelemetry-ext-jaeger/README.rst
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.jaeger
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. automodule:: opentelemetry.ext.jaeger.gen.jaeger.ttypes
+    :members:
+    :undoc-members:
+    :show-inheritance: