Provide example on using `libcnb.Detector` interface

[AidanDelaney]

Show a number of examples in increasing complexity. Each example introduces a single idea.

[AidanDelaney]

This starts to address #50. It's not reference documentation so I don't think it fits into the https://tip.golang.org/doc/comment model. This tutorial has a specific order to it (hence it's not reference documentation) in that it introduces very simple examples and incrementally adds complexity.

Would we prefer this tutorial-style documentation as a long comment on the Detector interface? Or is this not the right approach to addressing #50?

[dmikusa]

Would we prefer this tutorial-style documentation as a long comment on the Detector interface? Or is this not the right approach to addressing https://github.com/buildpacks/libcnb/issues/50?

I agree that it probably doesn't fit well into the Go docs. I'm sure you could stuff it into the Go docs somewhere, but there's not a clear place to put it. I'm OK with this being separate, with references to the Go docs where relevant.

I think the question to me is where to put it? The docs/ folder in the repo is one possibility, although, I have personally never found it all that helpful when projects do this. Less because of the location, being colocated with the code is reasonable, but more because it doesn't have a cohesive flow (or good search) and often seems like an afterthought.

If we want to keep it close to the code, I'd be more in favor of using a Github Wiki. I could also see the docs being a separate static web page, perhaps markdown generated. Any thoughts about either of those options?

Your examples are great, btw. They do lead me to another thought though, which is how to version the docs. With libcnb v2 on the horizon, we should also think about how we can structure things so that it's easy to find docs for the right version.

[AidanDelaney]

I think we should try the wiki approach. This would allow us to document v1 and then quickly restructure to v2 when that is released. @samj1912 do you want to enable wiki on this repo?

[samj1912]

@AidanDelaney I would instead prefer if we use https://go.dev/blog/examples#larger-examples

Wikis are generally not that discoverable for go docs and also likely to get stale.

[dmikusa]

@samj1912 I like that it compiles the examples, that's nice, but how flexible is it where the examples go?

The sample there, the sort package, just has some files referenced as examples in its package doc.

I'm struggling to visualize how this will fit as a doc comment. The additional context that @AidanDelaney has wrapped around the examples here is important and my concern is that you lose that with inline godoc. I'm also concerned about the volume of the content, there's quite a bit here and that's just for detect. Presumably, there will be something similar for build as well. Putting all of that into the docs is a lot of info right out of the gate. How much control do we have to organize this information?

[samj1912]

I thought we agreed that libcnb repo will only contain reference examples for using various APIs and that full tutorials will end up in buildpacks.io.

I would prefer not to create yet another divergence and use Wikis for user documentation. Wikis are generally not that visible, easy to test or automate or review.

With both the examples and the buildpacks.io website we get review and testing abilities for docs and being able to run it in a CI and they are also a lot more visible.

[samj1912]

The full examples also end up in files instead of doc comments -

for eg https://cs.opensource.google/go/go/+/master:src/sort/example_keys_test.go

renders the SortKeys example above.

[dmikusa]

I thought we agreed that libcnb repo will only contain reference examples for using various APIs and that full tutorials will end up in buildpacks.io.

I don't recall off the top of my head, mostly just reacting to the content in this PR. It seems like more tutorial and less documentation. I'm totally OK with having this on buildpacks.io docs.

[AidanDelaney]

I'm adding small examples of Detect and Build here. I'll move the tutorial style explanation to buildpacks.io/docs

[AidanDelaney]

When we're happy with this approach, I'll crate 1.x versions of these examples.

[AidanDelaney]

Hmm...I'm unsure why the Unit Test check is not re-running after a force push.

[dmikusa]

Hmm...I'm unsure why the Unit Test check is not re-running after a force push.

Not 100% sure. It should re-run. Maybe try resolving the conflict with go.mod/sum?