Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Synchronize OpenTelemetry Python code examples between otel-python and otel.io #4890

Open
zhihali opened this issue Jul 25, 2024 · 4 comments
Labels
bug Something isn't working sig:python

Comments

@zhihali
Copy link
Contributor

zhihali commented Jul 25, 2024

As discussed in the SIG meeting on July 25th(https://docs.google.com/document/d/1CIMGoIOZ-c3-igzbd6_Pnxx1SjAkjwqoYSUWxPY8XIs/edit), we need to implement a solution to ensure consistency between the OpenTelemetry Python code examples in our repository and the documentation on opentelemetry.io.

Current situation:

  • Python code examples exist in the OpenTelemetry Python repository
  • opentelemetry.io manually copies these examples for documentation(manually? correct me if I'm wrong)
  • This process is prone to inconsistencies, especially during version updates. if the python repo have change which will lead to problem in example code, we can’t find it in time, which could lead to confusions.

Proposed solution:
Implement a function or process that:

  1. Find a way to automatically syncs code examples from the Python repo to the documentation
  2. Ensures that examples in the documentation are always up-to-date
  3. Add testing of the code examples to catch any issues(this will be done in python repo)

Next steps:

  1. Research potential methods for automating this synchronization

This enhancement will improve the reliability of our documentation and reduce the manual effort required to keep code examples consistent across our ecosystem.

Related issues:
#4078

What is the name + path of the page that needs changed? The relative path
and page title where you found a problem.

https://opentelemetry.io/docs/languages/python/

I would like to implement the fix, welcome discuss!

@zhihali zhihali added the bug Something isn't working label Jul 25, 2024
@svrnm
Copy link
Member

svrnm commented Jul 26, 2024

Thanks for raising this issue!

We (SIG Comms) are currently testing tooling for syncing code between language repos and docs, we are still reluctant to talk about this in a broader forum, because we still need to figure out some of the processes and logistics, see #1635 for some additional details.

Currently Java & Go have some implementation of that, @zeitlinger for example created this PR the other day:

If @open-telemetry/python-maintainers want to provide something similar, I recommend that we start with getting started

I will try to find some time to write down some words about this tooling and more importantly the process we plan to implement.

@zhihali
Copy link
Contributor Author

zhihali commented Jul 26, 2024

@svrnm Thank you for the detailed explanation. I've reviewed PR #4642 and the related discussions, and it's clear this has been a topic of interest for some time.👍🏻
However, I have a few questions about the current implementation:

I see we have a 'tools' folder with configuration files, and 'code-excerpts' scripts defined in package.json.
However, I couldn't find any CI configuration that actually runs these tools automatically.

Given this, am I correct in understanding that this code synchronization feature is still in an experimental phase? It doesn't appear to be integrated into the regular workflow of the opentelemetry.io repository yet.
Could you clarify the current status of this feature and any plans for its full integration into the project's routine processes?

@svrnm
Copy link
Member

svrnm commented Jul 29, 2024

Given this, am I correct in understanding that this code synchronization feature is still in an experimental phase? It doesn't appear to be integrated into the regular workflow of the opentelemetry.io repository yet.
Could you clarify the current status of this feature and any plans for its full integration into the project's routine processes?

It's experimental, that's why it is not integrated more deeply yet, we have plans for full integration, but this is a massive undertaking and we have other big projects (especially localization) going on where we need to balance our resources. We are happy to take on help for that, but at the same time I have to call out, that this is not a trivial project and it requires a certain level of understanding how things are cobbled together for the website, so things are not likely to go smooth.

@zhihali
Copy link
Contributor Author

zhihali commented Jul 31, 2024

@svrnm Thank you for the detailed explanation! I understand the complexity and resource constraints. I'm comfortable with Python and willing to help where I can. Maybe I could start from opening a PR similar to Java, and try to run and test the tool? Let me know how I can best assist.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working sig:python
Projects
Status: Need Docs Review
Development

No branches or pull requests

2 participants