[Bug]: Documentation improvements

[JimDaly]

Component

General

Description

Reference documentation for this distro is now published at https://learn.microsoft.com/python/api/microsoft-opentelemetry/microsoft.opentelemetry

There are some opportunities for improving the docs, these can generally be fixed by asking CoPilot to fix the code comments and add missing descriptions.

This python-guidance.htm is a version of the guidance for developers that on-board new Python libraries.

Expected Behavior

1. There should be no broken links such as the one found in the first paragraph of the opentelemetry Package. It says:

   Provides a single entry-point — <xref:use_microsoft_opentelemetry> — that initialises OpenTelemetry global providers (tracing, metrics, logging) and optionally configures Azure Monitor as an exporter.

   <xref:use_microsoft_opentelemetry> should be a link to the use_microsoft_opentelemetry heading on the same page. It is likely broken because it doesn't use the fully qualified name of the function.

   Other examples from the build report include:

   • opentelemetry.a365.core.utils Cross reference not found: 'OpenTelemetryScope.inject_context_to_headers'
   • opentelemetry.a365.hosting.middleware.output_logging_middleware.OutputLoggingMiddleware Cross reference not found: 'microsoft.opentelemetry.a365.hosting.middleware.output_logging_middleware.OutputScope'
   • opentelemetry.a365.hosting.middleware.output_logging_middleware.OutputLoggingMiddleware Cross reference not found: 'A365_PARENT_TRACEPARENT_KEY'
   • opentelemetry.a365.hosting.middleware.OutputLoggingMiddleware Cross reference not found: 'microsoft.opentelemetry.a365.hosting.middleware.OutputScope'
   • opentelemetry.a365.hosting.middleware.OutputLoggingMiddleware Cross reference not found: 'A365_PARENT_TRACEPARENT_KEY'
   • opentelemetry.a365.hosting.OutputLoggingMiddleware Cross reference not found: 'microsoft.opentelemetry.a365.hosting.OutputScope'.
   • opentelemetry.a365.hosting.OutputLoggingMiddleware Cross reference not found: 'A365_PARENT_TRACEPARENT_KEY'.
   • opentelemetry Cross reference not found: 'use_microsoft_opentelemetry'.

2. Missing descriptions

   Examples:

   • a365 Package Packages. Why does the hosting package have a description an none of the others do?
   • FinishReason Enum. None of the members have descriptions. This seems to be true for most enums.

   Many more examples...

3. Missing content

   Examples:

   • agent365_exporter Module
   • constants Module
   • langchain Package
   • constants Module I created PR Add docstrings for constants for OpenTelemetry span operations and environment variables #210 to address this particular issue

4. Strange content

   populate_invoke_agent_scope Module populate function has this description:

   Populate all supported InvokeAgentScope tags from the provided TurnContext. :param scope: The InvokeAgentScope instance to populate. :param turn_context: The TurnContext containing activity information. :return: The updated InvokeAgentScope instance.

5. Vendored from microsoft-agents-a365-observability* descriptions

   Some descriptions have sentances that include Vendored from microsoft-agents-a365-observability*. I guess that this means they were copied from the corresponding A365 Observability type. But what does this mean and why do people care? They have chosen this distro and we can't expect that they are intersested in the one that isn't deprecated but probably will be soon. This is a very internal facing cescription, and we lose the opportunity to provide one that is customer centered.

Steps to Reproduce

Go to https://learn.microsoft.com/en-us/python/api/microsoft-opentelemetry/microsoft.opentelemetry and browse through the generated docs.

Environment

Not applicable

Additional Context

I expect that CoPilot could fix most of these issues. Please give it this file: python-guidance.htm

[github-actions]

cc @hectorhdzg @JacksonWeber @lzchen @MSNev @rads-1996 @jeremydvoss