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

alrex · web-flow · commit 64d0426f3b81 · 2021-05-07T14:10:44.000-07:00
diff --git a/CONTRIBUTING.md b/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.
 
diff --git a/dev-requirements.txt b/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
diff --git a/docs-requirements.txt b/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.
diff --git a/docs/conf.py b/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,
diff --git a/docs/examples/basic_context/README.rst b/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/>`.
diff --git a/docs/examples/basic_tracer/README.rst b/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/>`.
diff --git a/docs/examples/datadog_exporter/README.rst b/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.
 
diff --git a/docs/examples/django/README.rst b/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.
diff --git a/docs/examples/opencensus-exporter-tracer/README.rst b/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.
diff --git a/docs/examples/opentracing/README.rst b/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>`
diff --git a/docs/exporter/jaeger/jaeger.rst b/docs/exporter/jaeger/jaeger.rst
@@ -1,4 +1,4 @@
-Opentelemetry Jaeger Exporters
+OpenTelemetry Jaeger Exporters
 ==============================
 
 .. automodule:: opentelemetry.exporter.jaeger
diff --git a/docs/exporter/otlp/otlp.rst b/docs/exporter/otlp/otlp.rst
@@ -1,4 +1,4 @@
-Opentelemetry OTLP Exporters
+OpenTelemetry OTLP Exporters
 ============================
 
 .. automodule:: opentelemetry.exporter.otlp
diff --git a/docs/index.rst b/docs/index.rst
@@ -72,31 +72,31 @@ install <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>
 
 .. toctree::
     :maxdepth: 1
-    :caption: OpenTelemetry Python Packages
+    :caption: Core Packages
     :name: packages
 
     api/api
     sdk/sdk
 
 .. toctree::
     :maxdepth: 2
-    :caption: OpenTelemetry Exporters
+    :caption: Exporters
     :name: exporters
     :glob:
 
     exporter/**
 
 .. toctree::
     :maxdepth: 2
-    :caption: OpenTelemetry Shims
+    :caption: Shims
     :name: Shims
     :glob:
 
     shim/**
 
 .. toctree::
     :maxdepth: 1
-    :caption: OpenTelemetry Python Performance
+    :caption: Performance
     :name: performance-tests
     :glob:
 
diff --git a/opentelemetry-api/src/opentelemetry/util/_time.py b/opentelemetry-api/src/opentelemetry/util/_time.py
@@ -18,7 +18,7 @@
 if version_info.minor < 7:
     getLogger(__name__).warning(  # pylint: disable=logging-not-lazy
         "You are using Python 3.%s. This version does not support timestamps "
-        "with nanosecond precision and the Opentelemetry SDK will use "
+        "with nanosecond precision and the OpenTelemetry SDK will use "
         "millisecond precision instead. Please refer to PEP 546 for more "
         "information. Please upgrade to Python 3.7 or newer to use nanosecond "
         "precision." % version_info.minor

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Opentelemetry Jaeger Exporters`
	`1`	`+OpenTelemetry Jaeger Exporters`
`2`	`2`	`==============================`
`3`	`3`
`4`	`4`	`.. automodule:: opentelemetry.exporter.jaeger`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Opentelemetry OTLP Exporters`
	`1`	`+OpenTelemetry OTLP Exporters`
`2`	`2`	`============================`
`3`	`3`
`4`	`4`	`.. automodule:: opentelemetry.exporter.otlp`