Migrate website_docs back to website repo?

[chalin]

@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.

[ocelotl]

This will be discussed in today's meeting, @chalin ✌️

[chalin]

@ocelotl - and the decision was?

[lzchen]

@chalin
We did not come to a consensus as there are some outstanding questions.
How does submoduling work? What will the maintenance burden be like if we go this route, and do we still get all the advantages of doing (2) (languages other than English)?

[chalin]

How does submoduling work?

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.

What will the maintenance burden be like if we go this route,

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.

and do we still get all the advantages of doing (2) (languages other than English)?

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.

[owais]

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.

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?

[owais]

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.

[chalin]

Does the website have any tools or scripts we can include in our CI pipeline to detect these issues?

No, not currently.

Either that or can the website CI job automatically open issues in opentelemetry-python project when such failures occur?

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.

[owais]

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.

[chalin]

Concretely, here's an example of how things can break: #2170

[chalin]

... our CI pipeline to detect these issues?

No, not currently.

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. :) )

[chalin]

Closed by open-telemetry/opentelemetry.io#805