Add documentation of the API methods on Readme

[ppcano]

We have added more features to this project, and besides the examples, the documentation is missing.

It would be good to start with:

• documenting the existing APIs.
• describes how this extension wraps the k8s go client library.

[pablochacin]

@ppcano Do you have any guidelines on how this documentation should be done? Any existing extension I could use as a guideline?

[ppcano]

At this moment, we don't have a default or preferred way. Looping @javaducky

Below are two different approaches:

• https://github.com/grafana/xk6-loki
• https://github.com/grafana/k6-chaos

[javaducky]

Rather than including custom API documentation within the README and expose ourselves to "drift", we should simply include a link to the public API at pkg.go.dev.

We should however go through the code to ensure it is adequately documented to make the docs usable. This may be addressed with issue #46.

[javaducky]

Let's add a badge linking to the docs. Here's a Markdown snippet generated from go.dev site:

[![Go Reference](https://pkg.go.dev/badge/github.com/grafana/xk6-kubernetes.svg)](https://pkg.go.dev/github.com/grafana/xk6-kubernetes)

[ppcano]

@javaducky, correct me if I am wrong but pkg.go.dev is meant to be for the go documentation.

Additionally, we should figure out a format for the Javascript API that can be used as a reference for other k6 extensions.

[javaducky]

@ppcano, yes...that's true...I kinda forgot the target user for this documentation is the Javascript developer. Definitely open for suggestions on the best formatting there.

The fear is still there for drift of the documentation from the code; not sure if there is something that could be hooked into the CICD to generate the docs based upon code. Will have to dig into something.

[pablochacin]

I've found some projects (for example goreadme) for generating markdown from the godoc. The interesting part is that these projects use templates for formatting the output in markdown. I'm wondering if we could tweak those templates for generating JS style documentation (for example, changing the case of the functions and struct members).

This is the template for generating the documentation for a function

{{ define "functions" }}
{{ if .Funcs }}

## Functions

{{ range .Funcs }}

### func [{{ .Name }}]({{ urlOrName (index $.Files .Pos.File) }}#L{{ .Pos.Line }})

{{ inlineCode .Decl.Text }}

{{ doc .Doc }}

{{ template "examplesNoHeading" .Examples }}
{{ end }}

{{ end }}
{{ end }}

[ppcano]

I think we should not overcomplicate the docs at this moment. The initial goal is to show what the extension can do. imo, the list of APIs linking to the examples might be a good start.

I can work on this issue.

[ppcano]

PR -> #54

[pablochacin]

I agree we can start simple, but also agree with @javaducky this is not sustainable in the long run.

…

On Thu, May 19, 2022 at 11:18 AM Pepe Cano ***@***.***> wrote: I think we should not overcomplicate the docs at this moment. The initial goal is to show what the extension can do. imo, the list of APIs linking to the examples might be a good start. I can work on this issue. — Reply to this email directly, view it on GitHub <#15 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFP3A5NWL5BEIO6VSP34MDVKYBP5ANCNFSM5GNX2JAQ> . You are receiving this because you commented.Message ID: ***@***.***>

-- [image: Pablo Chacin on about.me] Pablo Chacin about.me/pablochacin <http://about.me/pablochacin>