docs: link example references to source files

docs/examples/basic_context/README.rst

@@ -4,9 +4,9 @@ Basic Context
 These examples show how context is propagated through Spans in OpenTelemetry. There are three different
 examples:
 
-* implicit_context: Shows how starting a span implicitly creates context.
-* child_context: Shows how context is propagated through child spans.
-* async_context: Shows how context can be shared in another coroutine.
+* :scm_web:`implicit_context.py <docs/examples/basic_context/implicit_context.py>`: Shows how starting a span implicitly creates context.
+* :scm_web:`child_context.py <docs/examples/basic_context/child_context.py>`: Shows how context is propagated through child spans.
+* :scm_web:`async_context.py <docs/examples/basic_context/async_context.py>`: Shows how context can be shared in another coroutine.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_context/>`.
 

docs/examples/basic_tracer/README.rst

@@ -3,8 +3,8 @@ Basic Trace
 
 These examples show how to use OpenTelemetry to create and export Spans. There are two different examples:
 
-* basic_trace: Shows how to configure a SpanProcessor and Exporter, and how to create a tracer and span.
-* resources: Shows how to add resource information to a Provider.
+* :scm_web:`basic_trace.py <docs/examples/basic_tracer/basic_trace.py>`: Shows how to configure a SpanProcessor and Exporter, and how to create a tracer and span.
+* :scm_web:`resources.py <docs/examples/basic_tracer/resources.py>`: Shows how to add resource information to a Provider.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_tracer/>`.
 

docs/examples/declarative-config/README.rst

@@ -67,23 +67,24 @@ Then start the Collector:
 Run the example
 ---------------
 
-Point the SDK at ``otel-config.yaml`` with ``OTEL_CONFIG_FILE`` and let
-auto-instrumentation apply it. No configuration code lives in ``app.py``:
+Point the SDK at :scm_web:`otel-config.yaml <docs/examples/declarative-config/otel-config.yaml>` with ``OTEL_CONFIG_FILE`` and let
+auto-instrumentation apply it. No configuration code lives in :scm_web:`app.py <docs/examples/declarative-config/app.py>`:
 
 .. code-block:: sh
 
     export OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml
     opentelemetry-instrument python app.py
 
 You should see the exported span in the Collector's debug output. The
-``instrumentation/development.python`` section in ``otel-config.yaml``
+``instrumentation/development.python`` section in
+:scm_web:`otel-config.yaml <docs/examples/declarative-config/otel-config.yaml>`
 activates the ``requests`` instrumentation so outgoing HTTP calls made by
-``app.py`` are automatically traced without any code changes.
+:scm_web:`app.py <docs/examples/declarative-config/app.py>` are automatically traced without any code changes.
 
 Environment variable substitution
 ----------------------------------
 
-``otel-config.yaml`` uses ``${DEPLOYMENT_ENVIRONMENT:-development}`` to read the
+:scm_web:`otel-config.yaml <docs/examples/declarative-config/otel-config.yaml>` uses ``${DEPLOYMENT_ENVIRONMENT:-development}`` to read the
 deployment environment from the environment, defaulting to ``development``. Set
 it before running to override:
 

docs/examples/django/README.rst

@@ -46,7 +46,7 @@ an ``opentelemetry.instrumentation.django.DjangoInstrumentor`` to instrument the
 
 Clone the ``opentelemetry-python`` repository and go to ``opentelemetry-python/docs/examples/django``.
 
-Once there, open the ``manage.py`` file. The call to ``DjangoInstrumentor().instrument()``
+Once there, open the :scm_web:`manage.py <docs/examples/django/manage.py>` file. The call to ``DjangoInstrumentor().instrument()``
 in ``main`` is all that is needed to make the app be instrumented.
 
 Run the Django app with ``python manage.py runserver --noreload``.

docs/examples/error_handler/README.rst

@@ -31,14 +31,22 @@ error handlers are installed: ``error_handler_0``  will handle
 
     $ pip install opentelemetry-sdk
     $ git clone https://github.com/open-telemetry/opentelemetry-python.git
+
+The two error handler packages are available:
+:scm_web:`error_handler_0 <docs/examples/error_handler/error_handler_0>`
+and
+:scm_web:`error_handler_1 <docs/examples/error_handler/error_handler_1>`.
+
+.. code-block:: sh
+
     $ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_0
     $ pip install -e opentelemetry-python/docs/examples/error_handler/error_handler_1
 
 Execution
 ---------
 
 An example is provided in the
-``opentelemetry-python/docs/examples/error_handler/example.py``.
+:scm_web:`example.py <docs/examples/error_handler/example.py>`.
 
 You can just run it, you should get output similar to this one:
 

docs/examples/fork-process-model/README.rst

@@ -15,6 +15,8 @@ The source code for the examples with Flask app are available :scm_web:`here <do
 Gunicorn post_fork hook
 -----------------------
 
+See the :scm_web:`Gunicorn configuration <docs/examples/fork-process-model/flask-gunicorn/gunicorn.conf.py>`.
+
 .. code-block:: python
 
     from opentelemetry import trace
@@ -41,6 +43,8 @@ Gunicorn post_fork hook
 uWSGI postfork decorator
 ------------------------
 
+See the :scm_web:`uWSGI application <docs/examples/fork-process-model/flask-uwsgi/app.py>`.
+
 .. code-block:: python
 
     from uwsgidecorators import postfork

docs/examples/logs/README.rst

@@ -28,7 +28,7 @@ Installation
 Run the Example
 ---------------
 
-Start the Collector locally to see data being exported. Write the following file:
+Start the Collector locally to see :scm_web:`otel-collector-config.yaml <docs/examples/logs/otel-collector-config.yaml>`:
 
 .. code-block:: yaml
 
@@ -61,6 +61,8 @@ Then start the Docker container:
         -v $(pwd)/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
         otel/opentelemetry-collector-contrib:latest
 
+Run :scm_web:`example.py <docs/examples/logs/example.py>`:
+
 .. code-block:: sh
 
     $ python example.py

docs/examples/metrics/views/README.rst

@@ -3,11 +3,11 @@ View common scenarios
 
 These examples show how to customize the metrics that are output by the SDK using Views. There are multiple examples:
 
-* change_aggregation.py: Shows how to configure to change the default aggregation for an instrument.
-* change_name.py: Shows how to change the name of a metric.
-* limit_num_of_attrs.py: Shows how to limit the number of attributes that are output for a metric.
-* drop_metrics_from_instrument.py: Shows how to drop measurements from an instrument.
-* change_reservoir_factory.py: Shows how to use your own ``ExemplarReservoir``
+- :scm_web:`change_aggregation.py <docs/examples/metrics/views/change_aggregation.py>`: Shows how to configure to change the default aggregation for an instrument.
+- :scm_web:`change_name.py <docs/examples/metrics/views/change_name.py>`: Shows how to change the name of a metric.
+- :scm_web:`limit_num_of_attrs.py <docs/examples/metrics/views/limit_num_of_attrs.py>`: Shows how to limit the number of attributes that are output for a metric.
+- :scm_web:`drop_metrics_from_instrument.py <docs/examples/metrics/views/drop_metrics_from_instrument.py>`: Shows how to drop measurements from an instrument.
+- :scm_web:`change_reservoir_factory.py <docs/examples/metrics/views/change_reservoir_factory.py>`: Shows how to use your own `ExemplarReservoir`.
 
 The source files of these examples are available :scm_web:`here <docs/examples/metrics/views/>`.
 

docs/examples/multi-destination-exporting/README.rst

@@ -41,8 +41,14 @@ Installation
     pip install opentelemetry-exporter-otlp-proto-http
     pip install opentelemetry-instrumentation-logging # For LoggingHandler
 
-Run the Example
----------------
+Run the Examples
+----------------
+
+Run:
+
+- :scm_web:`multi_destination_traces.py <docs/examples/multi-destination-exporting/multi_destination_traces.py>`
+- :scm_web:`multi_destination_metrics.py <docs/examples/multi-destination-exporting/multi_destination_metrics.py>`
+- :scm_web:`multi_destination_logs.py <docs/examples/multi-destination-exporting/multi_destination_logs.py>`
 
 .. code-block:: sh
 

docs/examples/opencensus-exporter-tracer/README.rst

@@ -30,7 +30,8 @@ services.
     docker-compose up
 
 
-Now, the example can be executed:
+Now, run the :scm_web:`collector.py <docs/examples/opencensus-exporter-tracer/collector.py>`
+example:
 
 .. code-block:: sh
 

docs/examples/opencensus-shim/README.rst

@@ -54,7 +54,7 @@ Alternatively, you can install the Python dependencies separately:
 Run the Application
 -------------------
 
-Start the application in a terminal.
+Start the :scm_web:`app.py <docs/examples/opencensus-shim/app.py>` application in a terminal.
 
 .. code-block:: sh
 

docs/examples/opentracing/README.rst

@@ -74,7 +74,7 @@ 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:
+To run the :scm_web:`main.py <docs/examples/opentracing/main.py>` script:
 
 .. code-block:: sh
 

docs/examples/sqlcommenter/README.rst

@@ -16,6 +16,9 @@ Run MySQL server
 
 A running MySQL server with general logs enabled will store query statements with context resulting from the sqlcommenter feature enabled in this example.
 
+Change into the :scm_web:`books_database <docs/examples/sqlcommenter/books_database>`
+directory:
+
 .. code-block:: sh
 
     cd books_database
@@ -32,7 +35,8 @@ Check that the run is working and the general log is available:
 Run OpenTelemetry Collector
 ---------------------------
 
-Running the OpenTelemetry collector will show the MySQL instrumentor's
+Running the OpenTelemetry collector using
+:scm_web:`collector-config.yaml <docs/examples/sqlcommenter/collector-config.yaml>` will show the MySQL instrumentor's
 comment-in-span-attribute feature, which this example has also enabled.
 
 .. code-block:: sh
@@ -55,8 +59,7 @@ dependencies of the sqlcommenter example:
         opentelemetry-instrumentation-mysql \
         mysql-connector-python
 
-Then, run this script, which instruments all mysql-connector calls with
-two sqlcommenter features opted in.
+Then, run the :scm_web:`instrumented_query.py <docs/examples/sqlcommenter/instrumented_query.py>` script, which instruments all mysql-connector calls with two sqlcommenter features opted in.
 
 .. code-block:: sh