Hosted k6 documentation

[ragnarlonn]

Along with launch of k6.io marketing site, we want to plug in a developer-friendly, inviting and useful documentation framework.

Let's start by discussing our options in terms of good and potential frameworks to leverage. What other open source projects or public documentation will be useful as reference to model our site from?

Checklist

• decide on documentation framework
• write/merge documentation
• merge/integrate with k6.io

Imported from https://trello.com/c/GKPwLLr1/120-hosted-k6-documentation

[ragnarlonn]

Emily Ekberg
This is actually rather pleasant to read, both for the JS API and the REST API
Dec 20 at 5:20 PM - Reply - Delete

David Rosen
I spent some time exploring Particle.io a while back - and really liked the way their docs and references were structured, see e.g. https://docs.particle.io/reference/api/#webhooks

Digging deeper via https://github.com/spark/docs, it seems this site is using http://www.metalsmith.io/. While Metalsmith doesn't look super-simple, it may potentially be interesting to consider for our overall site design as well?
Dec 20 at 12:21 AM - Reply - Add Link as Attachment - Delete

Emily Ekberg
I've been writing docs with JSDoc: http://usejsdoc.org/

I'm totally up for using another documentation generator if it turns out to be easier to customize though, I went through a bunch of different generators and it's mostly the first I could find that didn't have any showstopper bugs or weird opinions on code structure.
Dec 19 at 8:26 PM - Reply - Add Link as Attachment - Delete

[adr0sen]

OK, for now I suggest we go with existing JSDoc-based docs hosted on Github Pages, using the structure built by @uppfinnarn. Later if we find necessary, we can consider moving to some other docs-framework.

What do we need to do?

1. Configure our CI to run make docs, then commit the generated docs folder to gh-repo such that https://github.com/loadimpact/k6/tree/master/docs would always reference our latest docs - it's not clear to me how/where one would update circle.yml to enable this, and I suspect we need to configure CircleCI Read/Write access?
2. Publish docs-folder via GitHub Pages from our master-branch
3. Configure custom domain for http://docs.k6.io, then also configure redirect for http://k6.io

I lack admin-privileges on the GitHub repo so can not really move this forward. @uppfinnarn or @robingustafsson - can you please help by making me admin (at least temporarily)?

[liclac]

@adr0sen Done!

[adr0sen]

Planning to implement approach demonstrated by https://github.com/krlmlr/git-subbranch

(update as of Jan 13th, 2017)

[adr0sen]

I read up some more on best practices for this and found what seems a very simple approach as described in https://gist.github.com/cobyism/4730490, essentially using:

git add docs && git commit -m "<commit message>"
git subtree push --prefix docs origin gh-pages

=> gh-pages branch created, docs is deployed at http://loadimpact.github.io/k6/

Remaining steps:

• custom domain configuration ( @robingustafsson - believe I need access to Route53 for this, can you invite me?)
• enable make docs along with above two commands as a deployment step to CircleCI

[adr0sen]

Custom domain http://docs.k6.io is now enabled.
I'm unsuccessful in getting http://k6.io and http://www.k6.io to properly redirect to http://docs.k6.io, per this configuration.

Reading e.g. this, it seems we could use a S3 static web hosting to configure this through a 30X redirect:

Another option is to have S3 take care of the redirect.
On the S3 side, you will want to create a bucket with the same name as the domain that will be redirected. So if you want to use "example.com", then your bucket needs to be called exactly that. When your bucket has been created, head into the properties, open up the static website hosting section, and select "Redirect all requests to another host name". Enter "www.example.com".
In Route 53, add a new A record with the "Name" field left empty. Switch "Alias" to "Yes" for this record, and select your example.com bucket from the list that appears when you click the "Alias Target" text field.
Requests for example.com will now end up being handled by S3, which immediately issues a redirect to www.

I lack Route 53 permissions to move this forward - @robingustafsson, perhaps you can take care of this or else grant my user enough permission to create and configure S3 buckets?

[robingustafsson]

@adr0sen The k6.io and www.k6.io redirects to docs.k6.io have now been set up.

[ragnarlonn]

@adr0sen @robingustafsson @uppfinnarn Is it possible to close this issue now? If there is some automation lacking maybe we can just create a new issue for that?