Add mypy doc

[cartermp]

This came up before, but there was some recent conversation here that made me feel like we could do a quick doc explaining how to configure a mypy project: open-telemetry/opentelemetry-python#2591 (comment)

There's mention of potentially needing this in a project configuration file:

[mypy-opentelemetry.sdk.*]
implicit_reexport = True

I do not know if this is also necessary, but it should be easy to add if it is.

[chalin]

See inline copyedit comments. Thanks!

[chalin]

Broader comment: As it stands the added page is very specific. Might it make sense to add the content to another page (such as the Python landing page), or to generalize the page title? Just a thought, I'm ok if this lands with the current page addition if others are ok with that too.

[cartermp]

I'd like to get the @open-telemetry/python-approvers take on this being a specific page. One way to look at mypy is that it's analogous to TypeScript, which is to say it's a dialect of the same core/family of language. And as it turns out, there are some unique things to keep in mind when using it. We have the same thing to consider for the JS docs long-term as well.

[sk-]

There's mention of potentially needing this in a project configuration file:

[mypy-opentelemetry.sdk.*]
implicit_reexport = True

I do not know if this is also necessary, but it should be easy to add if it is.

This is absolutely necessary if you are using the strict option, because it enables the flag --no-implicit-reexport.

This seems to be required only for the sdk because it programmatically constructs the __all__ variable, as opposed to the api where the __all__ variable is explicitly defined.

Without this option one gets errors like the following:

app/otel.py:7: error: Module "opentelemetry.sdk.metrics" does not explicitly export attribute "MeterProvider"; implicit reexport disabled  [attr-defined]
app/otel.py:8: error: Module "opentelemetry.sdk.metrics.export" does not explicitly export attribute "PeriodicExportingMetricReader"; implicit reexport disabled  [attr-defined]
app/otel.py:13: error: Module "opentelemetry.sdk.metrics.view" does not explicitly export attribute "ExplicitBucketHistogramAggregation"; implicit reexport disabled  [attr-defined]

[cartermp]

@chalin and @svrnm your feedback should be addressed.

@open-telemetry/python-approvers any feedback on the doc?

[svrnm]

lgtm

[chalin]

@open-telemetry/python-approvers - any feedback on this?

[ocelotl]

@open-telemetry/python-approvers - any feedback on this?

Looks good to me initially. Just a few things:

Is the underlying intention of this documentation to explain how to use mypy in a "standalone" way? What I mean is that we use mypy as part of our regular testing process, we do this by runnning tox -e mypy. I can imagine someone wants to run mypy by themselves on OTel Python by I wonder what is the context behind doing so.

If the intent of running mypy is to make sure everything is ok in order to submit a PR to collaborate with the project (I imagine that is not the case), then this information should be here.

Regarding this comment, we actually should update the API to also dynamically generate the contents of __all__ to be consistent with the SDK.

[cartermp]

@ocelotl The intention here is around end-user use of the SDK when instrumenting. I also had a coworker try out otel-python for themselves in a flask app and they ran into the same issue, needing to add this to their configuration to unblock themselves.

[chalin]

Thanks all!