Restructure and split Flux and Helm op docs

CONTRIBUTING.md

@@ -18,8 +18,8 @@ the `blocked-needs-validation` label is removed, and the issue can be worked
 on.
 
 To set up Flux to test things, there's documentation about setting up a
-[standalone install](docs/install/get-started.md) and a [Helm
-install](docs/install/helm-get-started.md), which might be helpful.
+[standalone install](docs/tutorials/get-started.md) and a [Helm
+install](docs/tutorials/get-started-helm.md), which might be helpful.
 
 Please talk to us on Slack, if you should get stuck anywhere. We appreciate
 any help and look forward to talking to you soon!
@@ -73,10 +73,10 @@ This is a rough outline of how to prepare a contribution:
 
 ### How to build and run the project
 
-Refer to the [building doc](docs/development/building.md) to find out how to build from
+Refer to the [building doc](docs/contributing/building.md) to find out how to build from
 source.
 
-Refer to the [Get Started Developing](docs/development/get-started-developing.md) guide for a walkthrough on developing Flux locally.
+Refer to the [Get Started Developing](docs/contributing/get-started-developing.md) guide for a walkthrough on developing Flux locally.
 
 ### How to run the test suite
 

README.md

@@ -31,7 +31,7 @@ change is atomic and transactional, git has your audit log. Each transaction
 either fails or succeeds cleanly. You're entirely code centric and don't need
 new infrastructure.
 
-![Deployment Pipeline](docs/images/flux-cd-diagram.png)
+![Deployment Pipeline](docs/_files/flux-cd-diagram.png)
 
 [![CircleCI](https://circleci.com/gh/fluxcd/flux.svg?style=svg)](https://circleci.com/gh/fluxcd/flux)
 [![GoDoc](https://godoc.org/github.com/fluxcd/flux?status.svg)](https://godoc.org/github.com/fluxcd/flux)
@@ -48,7 +48,7 @@ Its major features are:
 
 - [Automated git → cluster synchronisation](/docs/introduction.md#automated-git-cluster-synchronisation)
 - [Automated deployment of new container images](/docs/introduction.md#automated-deployment-of-new-container-images)
-- [Integrations with other devops tools](/docs/introduction.md#integrations-with-other-devops-tools) ([Helm](/docs/helm/helm-integration.md) and more)
+- [Integrations with other devops tools](/docs/introduction.md#integrations-with-other-devops-tools) ([Helm](/docs/references/helm-operator-integration.md) and more)
 - No additional service or infrastructure needed - Flux lives inside your
   cluster
 - Straight-forward control over the state of deployments in the
@@ -101,19 +101,19 @@ Get started by browsing through the documentation below:
 - Background about Flux
   - [Introduction to Flux](/docs/introduction.md)
   - [FAQ](/docs/faq.md) and [frequently encountered issues](https://github.com/fluxcd/flux/labels/FAQ)
-  - [How it works](/docs/how-it-works.md)
+  - [How it works](/docs/references/blueprint.md)
   - [Considerations regarding installing Flux](/docs/install/index.md)
-  - [Flux <-> Helm integration](/docs/helm/helm-integration.md)
+  - [Flux <-> Helm integration](/docs/references/helm-operator-integration.md)
 - Get Started with Flux
-  - [Standalone Flux](/docs/install/get-started.md)
-  - [Flux using Helm](/docs/install/helm-get-started.md)
-  - [Automation: annotations and locks](/docs/using/annotations-tutorial.md)
+  - [Standalone Flux](/docs/tutorials/get-started.md)
+  - [Flux using Helm](/docs/tutorials/get-started-helm.md)
+  - [Automation: annotations and locks](/docs/tutorials/driving-flux.md)
 - Operating Flux
-  - [Using fluxctl to control Flux](/docs/using/fluxctl.md)
-  - [Helm Operator](/docs/helm/helm-operator.md)
+  - [Using fluxctl to control Flux](/docs/references/fluxctl.md)
+  - [Helm Operator](/docs/helm-operator/)
   - [Troubleshooting](/docs/troubleshooting.md)
   - [Frequently encountered issues](https://github.com/fluxcd/flux/labels/FAQ)
-  - [Upgrading to Flux v1](/docs/using/upgrading-to-1.0.md)
+  - [Upgrading to Flux v1](/docs/guides/upgrading-to-1.0.md)
 
 ### Integrations
 
@@ -142,7 +142,7 @@ To familiarise yourself with the project and how things work, you might
 be interested in the following:
 
 - [Our contributions guidelines](CONTRIBUTING.md)
-- [Build documentation](/docs/development/building.md)
+- [Build documentation](/docs/contributing/building.md)
 - [Release documentation](/internal_docs/releasing.md)
 
 ## <a name="help"></a>Getting Help

chart/flux/Chart.yaml

@@ -11,6 +11,6 @@ maintainers:
   - name: stefanprodan
     email: stefan@weave.works
 engine: gotpl
-icon: https://raw.githubusercontent.com/fluxcd/flux/master/docs/images/weave-flux.png
+icon: https://raw.githubusercontent.com/fluxcd/flux/master/docs/_files/weave-flux.png
 keywords:
   - gitops

chart/flux/README.md

@@ -22,7 +22,7 @@ This means fluxd can fail to apply changes to HelmRelease resources.
 ### Helm
 
 Tiller should be running in the cluster, though
-[helm-operator](../../docs/helm/helm-operator.md) will wait
+[helm-operator](../../docs/helm-operator/references/operator.md) will wait
 until it can find one.
 
 # Git repo
@@ -37,7 +37,7 @@ until it can find one.
 ## Installation
 
 We put together a simple [Get Started
-guide](../../docs/install/helm-get-started.md) which takes about 5-10 minutes to follow.
+guide](../../docs/tutorials/get-started-helm.md) which takes about 5-10 minutes to follow.
 You will have a fully working Flux installation deploying workloads to your cluster.
 
 ## Installing Flux using Helm
@@ -154,7 +154,7 @@ The [configuration](#configuration) section lists all the parameters that can be
 #### Setup Git deploy
 
 At startup Flux generates a SSH key and logs the public key.
-Find the SSH public key by installing [fluxctl](../../docs/using/fluxctl.md) and
+Find the SSH public key by installing [fluxctl](../../docs/references/fluxctl.md) and
 running:
 
 ```sh
@@ -288,8 +288,8 @@ The following tables lists the configurable parameters of the Flux chart and the
 | `helmOperator.affinity`                           | `{}`                                                 | Affinity properties for the helmOperator deployment
 | `kube.config`                                     | [See values.yaml](/chart/flux/values.yaml#L151-L165) | Override for kubectl default config in the Flux pod(s).
 | `prometheus.enabled`                              | `false`                                              | If enabled, adds prometheus annotations to Flux and helmOperator pod(s)
-| `syncGarbageCollection.enabled`                   | `false`                                              | If enabled, fluxd will delete resources that it created, but are no longer present in git (experimental, see [garbage collection](/docs/features/garbagecollection.md))
-| `syncGarbageCollection.dry`                       | `false`                                              | If enabled, fluxd won't delete any resources, but log the garbage collection output (experimental, see [garbage collection](/docs/features/garbagecollection.md))
+| `syncGarbageCollection.enabled`                   | `false`                                              | If enabled, fluxd will delete resources that it created, but are no longer present in git (experimental, see [garbage collection](/docs/references/garbagecollection.md))
+| `syncGarbageCollection.dry`                       | `false`                                              | If enabled, fluxd won't delete any resources, but log the garbage collection output (experimental, see [garbage collection](/docs/references/garbagecollection.md))
 
 Specify each parameter using the `--set key=value[,key=value]` argument to `helm install`. For example:
 

chart/flux/templates/NOTES.txt

@@ -3,7 +3,7 @@ Get the Git deploy key by either (a) running
   kubectl -n {{ .Release.Namespace }} logs deployment/{{ .Release.Name }} | grep identity.pub | cut -d '"' -f2
 
 or by (b) installing fluxctl through
-https://github.com/weaveworks/flux/blob/master/docs/using/fluxctl.md#installing-fluxctl
+https://github.com/weaveworks/flux/blob/master/docs/references/fluxctl.md#installing-fluxctl
 and running:
 
   fluxctl identity

deploy/flux-deployment.yaml

@@ -35,7 +35,7 @@ spec:
       # file, which you will need to do if you host your own git
       # repo rather than using github or the like. You'll also need to
       # mount it into the container, below. See
-      # https://github.com/weaveworks/flux/blob/master/docs/install/standalone-setup.md#using-a-private-git-host
+      # https://github.com/weaveworks/flux/blob/master/docs//guides/use-private-git-host.md
       # - name: ssh-config
       #   configMap:
       #     name: flux-ssh-config

docs/contributing/building.md

@@ -0,0 +1,33 @@
+# Building
+
+You'll need a working `go` environment version >= 1.11 (official releases are built against `1.12`).
+It's also expected that you have a Docker daemon for building images.
+
+Clone the repository. The project uses [Go Modules](https://github.com/golang/go/wiki/Modules),
+so if you explicitly define `$GOPATH` you should clone somewhere else.
+
+Then, from the root directory:
+
+```sh
+make
+```
+
+This makes Docker images, and installs binaries to `$GOBIN` (if you define it) or `$(go env GOPATH)/bin`.
+
+> **Note:** the default target architecture is amd64. If you would like
+> to try to build Docker images and binaries for a different
+> architecture you will have to set ARCH variable:
+>
+> ```sh
+> $ make ARCH=<target_arch>
+> ```
+
+## Running tests
+
+```sh
+# Unit tests
+make test
+
+# End-to-end tests
+make e2e
+```