various fixes to the documentation (open-telemetry#1828)

Author: alrex

CONTRIBUTING.md

@@ -19,7 +19,7 @@ This is the main repo for OpenTelemetry Python. Nevertheless, there are other re
 Please take a look at this list first, your contributions may belong in one of these repos better:
 
 1. [OpenTelemetry Contrib](https://github.com/open-telemetry/opentelemetry-python-contrib): Instrumentations for third-party
-   libraries and frameworks. There is an ongoing effort to migrate into the Opentelemetry Contrib repo some of the existing
+   libraries and frameworks. There is an ongoing effort to migrate into the OpenTelemetry Contrib repo some of the existing
    programmatic instrumentations that are now in the `ext` directory in the main OpenTelemetry repo. Please ask in the Slack
    channel (see below) for guidance if you want to contribute with these instrumentations.
 

dev-requirements.txt

@@ -4,9 +4,9 @@ isort~=5.8
 black~=20.8b1
 httpretty~=1.0
 mypy==0.812
-sphinx~=2.1
-sphinx-rtd-theme~=0.4
-sphinx-autodoc-typehints~=1.10.2
+sphinx~=3.5.4
+sphinx-rtd-theme~=0.5
+sphinx-autodoc-typehints
 pytest>=6.0
 pytest-cov>=2.8
 readme-renderer~=24.0

docs-requirements.txt

@@ -1,6 +1,8 @@
-sphinx~=2.4
-sphinx-rtd-theme~=0.4
+sphinx~=3.5.4
+sphinx-rtd-theme~=0.5
 sphinx-autodoc-typehints
+# used to generate docs for the website
+sphinx-jekyll-builder
 
 # Need to install the api/sdk in the venv for autodoc. Modifying sys.path
 # doesn't work for pkg_resources.

docs/conf.py

@@ -125,7 +125,15 @@
 # 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"]
+exclude_patterns = [
+    "_build",
+    "Thumbs.db",
+    ".DS_Store",
+    "examples/fork-process-model/flask-gunicorn",
+    "examples/fork-process-model/flask-uwsgi",
+    "examples/error_handler/error_handler_0",
+    "examples/error_handler/error_handler_1",
+]
 
 autodoc_default_options = {
     "members": True,

docs/examples/basic_context/README.rst

@@ -1,14 +1,11 @@
 Basic Context
 =============
 
-These examples show how context is propagated through Spans in OpenTelemetry.
-
-There are three different examples:
+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.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_context/>`.

docs/examples/basic_tracer/README.rst

@@ -1,12 +1,9 @@
 Basic Trace
 ===========
 
-These examples show how to use OpenTelemetry to create and export Spans.
-
-There are two different examples:
+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.
 
 The source files of these examples are available :scm_web:`here <docs/examples/basic_tracer/>`.

docs/examples/datadog_exporter/README.rst

@@ -1,5 +1,5 @@
-Datadog Exporter Example
-========================
+Datadog Exporter
+================
 
 These examples show how to use OpenTelemetry to send tracing data to Datadog.
 

docs/examples/django/README.rst

@@ -1,5 +1,5 @@
-OpenTelemetry Django Instrumentation Example
-============================================
+Django Instrumentation
+======================
 
 This shows how to use ``opentelemetry-instrumentation-django`` to automatically instrument a
 Django app.

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

@@ -1,5 +1,5 @@
-OpenTelemetry Collector Tracer OpenCensus Exporter Example
-==========================================================
+OpenCensus Exporter
+===================
 
 This example shows how to use the OpenCensus Exporter to export traces to the
 OpenTelemetry collector.

docs/examples/opentracing/README.rst

@@ -1,5 +1,5 @@
-OpenTracing Shim Example
-==========================
+OpenTracing Shim
+================
 
 This example shows how to use the :doc:`opentelemetry-opentracing-shim
 package <../../shim/opentracing_shim/opentracing_shim>`