Comments (10)
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.
from xk6-kubernetes.
At this moment, we don't have a default or preferred way. Looping @javaducky
Below are two different approaches:
from xk6-kubernetes.
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.
from xk6-kubernetes.
@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.
from xk6-kubernetes.
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 }}
from xk6-kubernetes.
@ppcano Do you have any guidelines on how this documentation should be done? Any existing extension I could use as a guideline?
from xk6-kubernetes.
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)
from xk6-kubernetes.
@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.
from xk6-kubernetes.
PR -> #54
from xk6-kubernetes.
from xk6-kubernetes.
Related Issues (20)
- xk6-kubernetes extension can't be used in-cluster HOT 3
- Allow login with server host and token HOT 1
- Bump dependencies and CI
- Arrays of objects returned by xk6-kubernetes do not have the length property
- Redesign scope of xk6-kubernetes API HOT 10
- Implement generic k8s interface
- Add support for deploying custom resources HOT 2
- Add helper function for creating random namespaces
- Add helper function for waiting a Deployment is ready
- Deleting namespace using the generic interface fails
- Re-implement generic Apply method using dynamic client's apply HOT 1
- Apply fails if the resources already exist HOT 1
- Add options parameter to Delete function in Generic API
- Ingresses missing from generic resource API
- Add examples for CRDs
- Remove Deprecated API
- Move helper functions to helpers package in new API
- TypeScript type definitions HOT 1
- Migrate example scripts from deprecated APIs
- Upgrade dependencies and CI to latest specs
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from xk6-kubernetes.