Reorganize documentation

[akx]

This PR:

• Reorganizes all the documentation to live underneath docs/
• Adds Mkdocs configuration (compatible with Read The Docs!) with Material Design styling courtesy of mkdocs-material.

Why we need it: As a devops person trying to configure ingress-nginx, I grew very frustrated about the seeming (dis)organization of the documentation. There were duplicate files, just random notes smattered into README.md, etc., which felt like a pain.

With this PR merged, someone (likely someone more involved with the project core) could set up Read The Docs to automatically generate a searchable, navigable doc site like this:

Please let me know if there's anything you'd like changed about the PR, or if you have questions! 🙇

[k8s-ci-robot]

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
• If you have done the above and are still having issues with the CLA being reported as unsigned, please email the CNCF helpdesk: [email protected]

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository. I understand the commands that are listed here.

[aledbf]

@akx first, thank you for doing this. Documentation is by far the weakest point of ingress-nginx.

Can you sign the CLA?

[akx]

@aledbf Just signed. :)

[aledbf]

Please add the header boilerplate like https://github.com/kubernetes/ingress-nginx/blob/master/hack/boilerplate/boilerplate.py

[antoineco]

This file is not linked properly (see live demo)

[akx]

http://ingress-nginx.acotten.com/deploy/rbac/

[akx]

That is, it's available in the menus. :)
Where did you find a broken link?

[antoineco]

I got a 404 when clicking on the corresponding link in the side menu, probably a cached response then!

[aledbf]

@akx please run ./hack/verify-boilerplate.sh to get the filename with errors

[antoineco]

Before this (awesome) PR gets merged, should we consider having that documentation hosted and automatically updated right away? @akx do you know if GitHub pages would be a good candidate?

[aledbf]

do you know if GitHub pages would be a good candidate?

I think this is the only option if we want to keep this up to date.

Edit: http://www.mkdocs.org/user-guide/deploying-your-docs/#github-pages

[antoineco]

Yup, you could have a new "Docs" Travis stage ;)

[akx]

@aledbf Boilerplate fixed. Apparently /usr/bin/env python3 wasn't alright, so I added an assertion to check the script is being run on Py3, not Py2.

Yes, Github Pages should be absolutely fine :) After all, it's just a static site.

[codecov-io]

Codecov Report

Merging #2413 into master will increase coverage by 0.12%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #2413      +/-   ##
==========================================
+ Coverage   40.92%   41.05%   +0.12%     
==========================================
  Files          74       74              
  Lines        5248     5252       +4     
==========================================
+ Hits         2148     2156       +8     
+ Misses       2807     2803       -4     
  Partials      293      293

Impacted Files	Coverage Δ
internal/file/filesystem.go	40.98% <0%> (-0.4%)	⬇️
internal/ingress/controller/nginx.go	5.09% <0%> (-0.02%)	⬇️
cmd/nginx/main.go	26.2% <0%> (+4.82%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 959d7b1...8aa9db8. Read the comment docs.

[aledbf]

/approve

[antoineco]

@akx there's a minor conflict to resolve due to the merging of #2409.

[akx]

@antoineco Rebased.

[antoineco]

/lgtm

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: akx, aledbf, antoineco

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 [aledbf]

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