Generate live project documentation using mkdocs and gh-pages

[aledbf]

Note: to build I need to remove docs/apireference directory. Can we move that directory?

Local test:

rm -rf docs/apireference
make live-docs

open browser localhost:3000

Create a detached branch:

git checkout --orphan gh-pages
git rm -rf .
touch .empty
git add .empty
git commit -m "Initial Commit"

After this step it is possible to build and publish the docs running:

GH_TOKEN=XXXXXX GH_REF=github.com/kubernetes/kops ./hack/publish-docs.sh

[aledbf]

/assign @justinsb

[aledbf]

@justinsb ping

[chrislovecnm]

Note: to build I need to remove docs/apireference directory. Can we move that directory?

Yes we can move it, but we need to fix apireference already. What is the purpose of this PR btw? I know what it does, but in the big picture what value are we getting?

[chrislovecnm]

I like this, and appreciate the work, but our goal has been to get our docs on kubernetes.io. I do not think other k8s projects are maintaining gh-pages. Thoughts?

[chrislovecnm]

aledbf/mkdocs:0.1

I am not a huge fan of pulling in external containers. I know you are maintaining this, but any other options?

[chrislovecnm]

We need 1.10 included

[chrislovecnm]

Why are we looking at gh-pages? We really need our docs on kubernetes.io :shrug

[aledbf]

I like this, and appreciate the work, but our goal has been to get our docs on kubernetes.io.

Who's working on that?

but our goal has been to get our docs on kubernetes.io.

I think the goal should be provide a better UX for user documentation, including search.

I do not think other k8s projects are maintaining gh-pages. Thoughts?

I already do this https://kubernetes.github.io/ingress-nginx/
This was the principal complaint from users (from the survey https://docs.google.com/forms/d/e/1FAIpQLSdcqdfMbuJHeQQe6hB7iU7sf3q9qZlrrXtrwGPlS7sicOpICA/viewform)
Since the publication of the site, we have more metrics about that they search, how they browse the docs and most importantly we now double the number of contributions improving documentation.

[aledbf]

@chrislovecnm I can close this PR if the goal is to get the docs on kubernetes.io

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: aledbf
To fully approve this pull request, please assign additional approvers.
We suggest the following additional approver: justinsb

If they are not already assigned, you can assign the PR to them by writing /assign @justinsb in a comment when ready.

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[justinsb]

This is awesome, thank you @aledbf . We'll have to reorg our docs a little, but I think people want to do that anyway. I'm going to go ahead and merge this so we can get the reorg started :-)