WIP - Provide documentation for keda.sh

[tomkerkhove]

Provide documentation for keda.sh based on Hugo & syna template. The template is included via a sub-module in Git based on the official Hugo guidance which is blowing up the PR, sorry for that.

Once Netlify is setup, every PR will include a preview version of the docs.

• Provide documentation skeleton with syna theme
• Provide landing page
• Provide scaler overview
• Provide getting started
• Provide deployment guidance
• Migrate all scalers
  • Samples
  • Docs
• Setup doc hosting on Netlify
  • Configure Netlify app on repo (@jeffhollan)
  • Create Netlify site (@jeffhollan)
  • Configure deployment (docs\netlify.toml)
• Provide documentation
  • How to run docs locally
  • How to write docs for new scalers

Follow-up:

• Create issue for docs on Operator deployment
• Remove the wiki
• Setup DNS for keda.sh to route to Netlify (@jeffhollan)

[tomkerkhove]

PR Experience

The PR experience will look like this:

This gives you a preview URL to see the changes:

If @jeffhollan would be up for it, we could add a banner at the top saying it's just a preview not the official stuff like this:

Preview Banner

This is just for @jeffhollan but you can go here:

And use this snippet:

Preview Content snippet

<style>
.alert {
    padding: 20px;
    background-color: #2196F3;
    color: white;
}

.closebtn {
    margin-left: 15px;
    color: white;
    font-weight: bold;
    float: right;
    font-size: 22px;
    line-height: 20px;
    cursor: pointer;
    transition: 0.3s;
}

.closebtn:hover {
    color: black;
}
</style>

<div class="alert">
This is a preview.
</div>

[ahmelsayed]

It looks great to me :) Thank you very much @tomkerkhove for the awesome stuff!

@jeffhollan I wonder if it'll be better to move this to a keda-docs or kedacore-docs repo

[jeffhollan]

Yeah I’m fine if we break it out. My only thinking of the benefit of having in one spot is that when people open up a PR for something like a scaler we can have them have the docs as part of the same PR. But we can obviously enforce that across repos too - just something we’ll need to let people know to link related PRs for docs / code.

[jeffhollan]

Yeah @tomkerkhove just playing with Netlify. I wonder if we move these commits over to kedacore/keda-docs and will just include in the contributor guide you need to update docs as well. Let me create

[jeffhollan]

@tomkerkhove I created the repo and gave you write permissions. I also hooked up Netlify for that repo.

https://github.com/kedacore/keda-docs

[tomkerkhove]

I agree with Jeff on this. If it's a seperate repo it's harder to have good docs. I use the approach of the PR for Promitor.io and when somebody creates a PR it includes feature, tests and docs - Good to go! Here there is more friction and a higher contribution barrier, or docs will just be ignored

[tomkerkhove]

Example of the contribution flow: tomkerkhove/promitor#766

PR validates build, tests and generates preview of docs.

[jeffhollan]

At first I was thinking docs was just a nested folder of markdown files, but there’s a lot of additional files here and folks may make changes to site without repo. I think my thinking now is we have a separate repo for the site : docs and just enforce folks link PRs for docs on new scalers.

[tomkerkhove]

At first I was thinking docs was just a nested folder of markdown files, but there’s a lot of additional files here and folks may make changes to site without repo.

Do you mean the files for the template or?

[jeffhollan]

I just mean files for the docs plus files for the website. It feels like a lot of changed files were pushing in when I think we can still enforce right behavior but not have a JavaScript single page app nested inside a Kubernetes deployment. This PR has like 1k+ files

[tomkerkhove]

That's correct and is due to the template which should be a one off thing which I think is fine, but if you guys want it seperate that's fine for me - Just very doubtful that we'll have parity in our docs 😁

[tomkerkhove]

So I'll move it then or?

[jeffhollan]

Let’s move for now and I may even setup a GitHub action that labels until docs are linked with some hashtag or something. If ends up drifting over time we can always move back. keda.sh alreadh hooked up To the docs repo and you have merge rights so let me know if you can pop over there. I can too today with this branch. Let me know

[tomkerkhove]

Ok, I'll commit the template to new repo and open PR for content review!

[tomkerkhove]

Boilerplate doc PR has been sent with mainly basic structure and template, more details to follow in follow-up PR.

kedacore/keda-docs#2

[ahmelsayed]

@tomkerkhove we can close this, right?