Add document sources from google repository

[sjs994]

• Added the document source as it is.
• Updated links to point to open-telemetry github repository.

Next step would be to generate the document and push it into gh-pages branch.

[sjs994]

Hi @aabmass, @lonewolf3739 can you take a look here

[srikanthccv]

@sjs994 Why are we adding large number of files? There are so many static html, js etc... Can we just add the markdown files and publish the generated content?

[sjs994]

@sjs994 Why are we adding large number of files? There are so many static html, js etc... Can we just add the markdown files and publish the generated content?

Thanks for this. I was not planning to make any change to the current source as it is except few renames. But it seems, there are too many unnecessary files. We would need the static contents like images, but i am really not sure why many bower_components are present in the previously checked-in code. I am taking a look at that.

[aabmass]

I see doc/themes/docdock/ has most of the files in this PR. I'm not too familiar with Hugo but it looks like it was previosuly vendored into here instead of submoduled and maybe has some patches . Although it's really hard to tell :/

I wonder if we could use the submodule as described here

[sjs994]

@aabmass I am also not too familiar with hugo. I guess it was used as mentioned in the third approach (extracting from the zip) in the link you shared.

Will give it a try to integrate it as a submodule.

[SergeyKanzhelev]

Generally speaking, there is no need to use huge, maybe just keep all the markdown files?

[sjs994]

@SergeyKanzhelev There are a bunch of markdown files, which seems to give a basic walkthrough on how to use the library: https://github.com/open-telemetry/opentelemetry-sqlcommenter/blob/main/README.md.

These is more of a detailed document, explaining the specs, tutorials for most of the ORMs, seems to be analogous to https://opentelemetry.io/docs.

Hugo creates an website, which feels user friendly: https://google.github.io/sqlcommenter than plain markdown files.

How about keeping this document source code in a separate branch. In that way we won't pollute the main branch files and commits, like how it was there in google repository: https://github.com/google/sqlcommenter/tree/gh-pages ?

[SergeyKanzhelev]

How about keeping this document source code in a separate branch.

You decide what's best. In my experience keeping things in separate branch is messy and creates an overhead.

I signed off on initial PR because I expected it will be followed by clean ups.

Hugo creates an website, which feels user friendly: https://google.github.io/sqlcommenter than plain markdown files.

Ultimately we want at least a subset of these specs on specification repository where everything is just a markdown. So I wouldn't worry about it too much.

[sjs994]

Thanks @SergeyKanzhelev

I signed off on initial PR because I expected it will be followed by clean ups.

Yeah that was the plan, but it added ~3k files which seems like we will be adding too much unnecessary files into the repository's version tree.

Ultimately we want at least a subset of these specs on specification repository where everything is just a markdown. So I wouldn't worry about it too much.

That makes sense. Now, if that's the case, we can strengthen the current md files example, picking the ones required from the document instead of adding any new files.

[sjs994]

Closing this PR as we are moving to plain markdown files as documentations.

[sjs994]

Thanks everyone for the review :)