Add ability to view documentation by version (#2628)

**What this PR does / why we need it**:
![Screen Shot 2021-10-13 at 13 54 47](https://user-images.githubusercontent.com/1751755/137069823-dc10f77a-5447-487e-bc9c-68b9fd030233.png)

Which files should be reviewed?

- docs/config.toml
- docs/assets/js/navbar-version-selector.js
- https://github.com/pipe-cd/pipe/blob/7fdbcd88298d9026e41c980e9c43a68287cd16d5/hack/prepare-release.sh#L39-L77

**Which issue(s) this PR fixes**:

Fixes #

**Does this PR introduce a user-facing change?**:
<!--
If no, just write "NONE" in the release-note block below.
-->
```release-note
NONE
```

This PR was merged by Kapetanios.

docs/assets/js/navbar-version-selector.js

@@ -0,0 +1,20 @@
+(function ($) {
+    'use strict';
+
+    var Selector = {
+        init: function () {
+            $(document).ready(function () {
+                const paths = window.location.pathname.split("/").filter(p => p)
+                if (paths.length === 0) {
+                    return
+                }
+                const version = paths[0].replace('docs', '').replace("-", '');
+                if (version) {
+                    $('.navbar-version-menu')[0].text = version;
+                };
+            });
+        },
+    };
+
+    Selector.init();
+}(jQuery));

docs/config.toml

@@ -86,7 +86,7 @@ privacy_policy = "https://github.com/pipe-cd/pipe/blob/master/LICENSE"
 
 # Menu title if your navbar has a versions selector to access old versions of your site.
 # This menu appears only if you have at least one [params.versions] set.
-version_menu = "Releases"
+version_menu = ""
 
 # Repository configuration (URLs for in-page links to opening issues and suggesting changes)
 github_repo = "https://github.com/pipe-cd/pipe"
@@ -159,3 +159,13 @@ no = 'Sorry to hear that. Please <a href="https://github.com/pipe-cd/pipe/issues
 	url = "mailto:pipecd.dev@gmail.com"
 	icon = "fa fa-envelope"
         desc = "Discuss development issues around the project"
+
+# Append the release versions here.
+[[params.versions]]
+  version = "dev"
+  githubbranch = "master"
+  url = "/docs-dev/"
+
+[[params.versions]]
+  version = "v0.18.0"
+  url = "/docs-v0.18.0/"

docs/content/en/docs-dev/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Welcome to PipeCD"
+linkTitle: "Documentation [dev]"
+type: docs
+---

docs/content/en/docs-dev/concepts/_index.md

@@ -0,0 +1,80 @@
+---
+title: "Concepts"
+linkTitle: "Concepts"
+weight: 2
+description: >
+  This page describes several core concepts in PipeCD.
+---
+
+### Piped
+
+`piped` (the ’d’ is short for ’daemon’) is a single binary component you run in your cluster, your local network to handle the deployment tasks.
+It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment.
+This component is designed to be stateless, so it can also be run in a single VM or even your local machine.
+
+### Control Plane
+
+A centralized component managing deployment data and provides gPRC API for connecting `piped`s as well as all web-functionalities of PipeCD such as
+authentication, showing deployment list/details, application list/details, delivery insights...
+
+### Project
+
+A project is a logical group of applications to be managed by a group of users.
+Each project can have multiple `piped` instances from different clouds or environments.
+
+There are three types of project roles:
+
+- **Viewer** has only permissions of viewing to deployment and application in the project.
+- **Editor** has all viewer permissions, plus permissions for actions that modify state such as manually trigger/cancel the deployment.
+- **Admin** has all editor permissions, plus permissions for managing project data, managing project `piped`.
+
+### Application
+
+A collect of resources (containers, services, infrastructure components...) and configurations that are managed together.
+PipeCD supports multiple kinds of applications such as `KUBERNETES`, `TERRAFORM`, `ECS`, `CLOUDRUN`, `LAMBDA`...
+
+### Environment
+
+An environment is a logical group of applications of a project. A project can have multiple environments.
+Each application must belong to one and only one environment. While each piped must belong to at least one environment.
+
+### Deployment
+
+A deployment is a process that does transition from the current state (running state) to the desired state (specified state in Git) of a specific application.
+When the deployment is success, it means the running state is synced with the desired state specified in the target commit.
+
+### Deployment Configuration
+
+A `.pipe.yaml` yaml file that contains configuration data to define how to deploy the application.
+Each application requires one deployment configuration file at application directory in the Git repository.
+
+### Application Directory
+
+A directory in Git repository containing deployment configuration file (`.pipe.yaml`) and application manifests.
+Each application must have one application directory.
+
+### Quick Sync
+
+Quick sync is a fast way to sync application to the state specified in a Git commit without any progressive strategy or manual approving. Its pipeline contains just only one predefined `SYNC` stage. For examples:
+- quick sync a Kubernetes application is just applying all manifests
+- quick sync a Terraform application is automatically applying all detected changes
+- quick sync a CloudRun/Lambda application is rolling out the new version and routing all traffic to it
+
+### Pipeline
+
+A list of stages specified by user in the deployment configuration file that tells `piped` how the application should be deployed. If the pipeline is not specified, the application will be deployed by Quick Sync way.
+
+### Stage
+
+A temporary middle state between current state and desired state of a deployment process.
+
+### Cloud Provider
+
+PipeCD supports multiple clouds and multiple kinds of applications.
+Cloud Provider defines which cloud and where application should be deployed to.
+
+Currently, PipeCD is supporting these five cloud providers: `KUBERNETES`, `ECS`, `TERRAFORM`, `CLOUDRUN`, `LAMBDA`.
+
+### Analysis Provider
+An external product that provides metrics/logs to evaluate deployments, such as `Prometheus`, `Datadog`, `Stackdriver`, `CloudWatch` and so on.
+It is mainly used in the [Automated deployment analysis](/docs/user-guide/automated-deployment-analysis/) context.

docs/content/en/docs-dev/contribution-guidelines/_index.md

@@ -0,0 +1,7 @@
+---
+title: "Contributor Guide"
+linkTitle: "Contributor Guide"
+weight: 6
+description: >
+  This guide is for anyone who want to contribute to PipeCD project. We are so excited to have you!
+---

docs/content/en/docs-dev/contribution-guidelines/architectural-overview.md

@@ -0,0 +1,33 @@
+---
+title: "Architectural overview"
+linkTitle: "Architectural overview"
+weight: 3
+description: >
+  This page describes the architecture of PipeCD.
+---
+
+![](/images/architecture-overview.png)
+<p style="text-align: center;">
+Component Architecture
+</p>
+
+### Piped
+
+A single binary component runs in your cluster, your local network to handle the deployment tasks.
+It can be run inside a Kubernetes cluster by simply starting a Pod or a Deployment.
+This component is designed to be stateless, so it can also be run in a single VM or even your local machine.
+
+### Control Plane
+
+A centralized component manages deployment data and provides gPRC API for connecting `piped`s as well as all web-functionalities of PipeCD such as
+authentication, showing deployment list/details, application list/details, delivery insights...
+
+Control Plane contains the following components:
+- `server`: a service to provide api for piped, web and serve static assets for web.
+- `cache`: a redis cache service for caching internal data.
+- `datastore`: data storage for storing deployment, application data
+  - this can be a fully-managed service such as `Firestore`, `Cloud SQL`...
+  - or a self-managed such as `MySQL`
+- `filestore`: file storage for storing logs, application states
+  - this can a fully-managed service such as `GCS`, `S3`...
+  - or a self-managed service such as `Minio`

docs/content/en/docs-dev/contribution-guidelines/contributing.md

@@ -0,0 +1,33 @@
+---
+title: "Contributing"
+linkTitle: "Contributing"
+weight: 1
+description: >
+  This page describes how to contribute to PipeCD.
+---
+
+PipeCD is an open source project that anyone in the community can use, improve, and enjoy. We'd love you to join us! 
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License Agreement ("CLA") described at [pipe-cd/pipe/master/CLA.md](https://github.com/pipe-cd/pipe/blob/master/CLA.md). You (or your employer) retain the copyright to your contribution; this simply gives us permission to use and redistribute your contributions as part of the project.
+
+You generally only need to sign a CLA once, so if you've already signed one, you probably don't need to do it again.
+
+In case you have not signed yet, [pipecd-bot](https://github.com/pipecd-bot) will guide you to sign the CLA _when you send the first pull request to [pipe-cd/pipe](https://github.com/pipe-cd/pipe) repository_.
+
+## Creating an issue
+
+If you've found a problem, please create an issue in the [pipe-cd/pipe](https://github.com/pipe-cd/pipe/issues) repository.
+
+## Creating a pull request
+
+Look at our [help wanted issues](https://github.com/pipe-cd/pipe/issues?q=is%3Aissue+is%3Aopen+label%3A"help+wanted") or our [good first issues](https://github.com/pipe-cd/pipe/issues?q=is%3Aissue+is%3Aopen+label%3A"good+first+issue") for finding some good issues for your first pull request.
+
+### Small tips
+
+The pull request title is used to generate our release changelog. Therefore, it would be great if you write the title that is easier to understand from the user's point of view.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We use GitHub pull requests for this purpose. Consult [GitHub Help](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) for more information on using pull requests.

docs/content/en/docs-dev/contribution-guidelines/control-plane-development.md

@@ -0,0 +1,57 @@
+---
+title: "Control plane development"
+linkTitle: "Control plane development"
+weight: 5
+description: >
+  This page describes where to find control-plane source code and how to run it locally for debugging.
+---
+
+## Source code structure
+
+- [cmd/pipecd](https://github.com/pipe-cd/pipe/tree/master/cmd/pipecd): entrypoint for binary of control-plane server.
+- [pkg/app/api](https://github.com/pipe-cd/pipe/tree/master/pkg/app/api): contains source code for control-plane api.
+- [pkg/app/web](https://github.com/pipe-cd/pipe/tree/master/pkg/app/web): contains source code for control-plane web.
+- [pkg](https://github.com/pipe-cd/pipe/tree/master/pkg): contains shared source code for all components of both `piped` and `control-plane`.
+
+## How to run control-plane locally
+
+### Prerequisites
+- Installing [kind](https://kind.sigs.k8s.io/docs/user/quick-start/#installation)
+- Running a local Kubernetes cluster by `make kind-up`. (Cluster that is no longer used can be deleted by `make kind-down`.)
+
+### Pushing the images to local container registry
+
+``` console
+make push
+```
+
+**NOTE: Since it uses the commit hash as an image tag, you need to make a new commit whenever you change the source code.**
+
+This command compiles the local source code to build the docker images for `pipecd`, `piped` and then pushes them to the local container registery which was enabled by `make kind-up`.
+
+### Rendering the local manifests
+
+Because the `manifests` directory at [pipe-cd/pipe](https://github.com/pipe-cd/pipe) are just containing the manifest templates, they cannot be used to install directly. The following command helps rendering those templates locally. The installable manifests will be stored at `.rendered-manifests` directory.
+
+``` console
+make render-manifests
+```
+
+#### Installing control-plane into the local cluster
+
+Now, you can use the rendered manifests at `.rendered-manifests` to install control-plane to the local cluster.
+
+Here is the command to install [quickstart](/docs/quickstart/)'s control-plane:
+
+``` console
+helm -n pipecd install pipecd .rendered-manifests/pipecd --dependency-update --create-namespace --values ./quickstart/control-plane-values.yaml
+```
+
+Once all components are running up, use `kubectl port-forward` to expose the installed control-plane on your localhost:
+
+``` console
+kubectl -n pipecd port-forward svc/pipecd 8080
+```
+
+Point your web browser to [http://localhost:8080](http://localhost:8080) to login with the configured static admin account: project = `quickstart`,
+username = `hello-pipecd`, password = `hello-pipecd`.

docs/content/en/docs-dev/contribution-guidelines/development.md

@@ -0,0 +1,38 @@
+---
+title: "Development"
+linkTitle: "Development"
+weight: 2
+description: >
+  This page describes how to build, test PipeCD source code at your local environment.
+---
+
+## Prerequisites
+
+Only `bazel` is required to build and test `PipeCD` project, but you don't need to install `bazel` directly.
+Instead of that we are using [`bazelisk`](https://github.com/bazelbuild/bazelisk) for automatically picking a good version of Bazel for building `PipeCD` project.
+
+You can install `bazelisk` by `go get` as the following:
+```
+go get github.com/bazelbuild/bazelisk
+```
+
+or directly install its [binary](https://github.com/bazelbuild/bazelisk/releases) from the release page.
+For more information, you might want to read the [installation notes of `bazelisk`](https://github.com/bazelbuild/bazelisk#requirements).
+
+## Repositories
+- [pipe](https://github.com/pipe-cd/pipe): contains all source code and documentation of PipeCD project.
+- [manifests](https://github.com/pipe-cd/manifests): contains all automatically generated release manifests for both `piped` and `control-plane` components.
+- [examples](https://github.com/pipe-cd/examples): contains various generated examples to demonstrate how to use PipeCD.
+
+## Build and test with Bazel
+
+- `make build`: builds all binaries in tree.
+- `make test`: runs all unit tests.
+- `make dep`: updates `go.mod` and bazel `WORKSPACE`. Run this command after adding a new go dependency or update the version of a dependency.
+- `make gazelle`: generates `BUILD.bazel` files for go code. Run this command after adding a new `import` in go code or adding a new go file.
+- `make buildifier`: formats bazel BUILD and .bzl files with a standard convention.
+- `make clean`: cleans all bazel cache.
+- `make expose-generated-go`: exposes generated Go files (`.pb.go`, `.mock.go`...) to editors and IDEs.
+- `make site`: runs PipeCD site (https://pipecd.dev) locally (requires [hugo](https://github.com/gohugoio/hugo) with `_extended` version `0.88.1` or later to be installed).
+
+**NOTE**: The first time of running a bazel command will take some minutes because bazel needs to download all required dependencies. From the second time it will be very fast.

docs/content/en/docs-dev/contribution-guidelines/piped-development.md

@@ -0,0 +1,37 @@
+---
+title: "Piped development"
+linkTitle: "Piped development"
+weight: 4
+description: >
+  This page describes where to find piped source code and how to run it locally for debugging.
+---
+
+## Source code structure
+
+- [pkg/app/piped](https://github.com/pipe-cd/pipe/tree/master/pkg/app/piped): contains source code for only `piped`.
+- [cmd/piped](https://github.com/pipe-cd/pipe/tree/master/cmd/piped): entrypoint for `piped` binary.
+- [pkg](https://github.com/pipe-cd/pipe/tree/master/pkg): contains shared source code for all components of both `piped` and `control-plane`.
+
+## How to run it locally
+
+1. Prepare the piped configuration file `piped-config.yaml`
+
+2. Ensure that your `kube-context` is connecting to the right kubernetes cluster
+
+2. Run the following command to start running `piped`
+
+``` console
+bazelisk run --run_under="cd $PWD && " //cmd/piped:piped -- piped \
+--tools-dir=/tmp/piped-bin \
+--config-file=piped-config.yaml
+```
+
+## How to run it locally as docker container
+
+``` bash
+# Compile the current source code to build a new Docker image
+# and then load it into the local docker client as bazel/cmd/piped:image.
+make load-piped-image
+
+docker run bazel/cmd/piped:image --help
+```