-
Notifications
You must be signed in to change notification settings - Fork 622
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
Migrate website_docs back to website repo? #2116
Comments
This will be discussed in today's meeting, @chalin ✌️ |
@ocelotl - and the decision was? |
@chalin |
One way to think of a submodule is as a git-aware "symbolic link" into another repo, at a specific commit. For OTel website examples of submodules, see https://github.com/open-telemetry/opentelemetry.io/tree/main/content-modules.
You'll need to periodically let the website team know when you'd like your SIG's submodule to be updated in the website repo — so that more recent website_docs can be used.
No. For one thing, the website team will only support doc versions if your docs are in the website repo. (This may or may not be a feature your SIG is interested in.) Another thing to consider is that you won't know if there's a build/markdown problem with your doc pages until the website build is run -- which will happen only when your SIG's submodule is updated. Let me know if you have other questions. |
Does the website have any tools or scripts we can include in our CI pipeline to detect these issues? Either that or can the website CI job automatically open issues in opentelemetry-python project when such failures occur? |
Other than the possibility of us not noticing bad markdown until the website build job runs or worse the website gets published with malformed markup, I don't see a problem with the submodule approach. |
No, not currently.
That will be addressed via open-telemetry/opentelemetry.io#542. So it won't be automatic, but if a reader sees an issue with a Python doc page, the Create documentation issue button will create the issue over this repo, not the website repo. |
The workflow sounds fine to me. I suppose lack of automation and tooling is not a big concern as they can be added later if we feel too much pain. |
Concretely, here's an example of how things can break: #2170 |
After, open-telemetry/opentelemetry.io#805 gets merged, you'll be able to define a GH action that checks out the website repo, updates the OTel Python submodule (to either HEAD or a PR's branch), builds the website and checks links. That would offer be at least a smoke test, but it wouldn't trip on issues like #2170. (It is interesting to consider that once open-telemetry/opentelemetry.io#805 gets merged it in effect could be considered a monorepo-like structure. So you could alway be working from the website repo. That way you can make changes to otel-python and check docs at the same time. Of course, it's a round about way to do things, but it is feasible. :) ) |
Closed by open-telemetry/opentelemetry.io#805 |
@ocelotl and @open-telemetry/python-maintainers:
As @austinlparker explained at the maintainer's meeting this week, you need to chose how you'd like the Python docs to be published by opentelemetry.io. The docs are currently under website_docs, which originally setup via #1724.
For details concerning your 2 choices, see open-telemetry/opentelemetry.io#730.
Let us know what your choice is, either in this issue or open-telemetry/opentelemetry.io#730.
The text was updated successfully, but these errors were encountered: