Sunday hacking.

Signed-off-by: Bartek Plotka <bwplotka@gmail.com>
adrien-f · Mar 31, 2019 · e18d65d · e18d65d
1 parent 14b2df0
commit e18d65d
Show file tree

Hide file tree

Showing 25 changed files with 197 additions and 69 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,4 +17,6 @@ data/
 
 /.idea
 /*.iml
+
 website/public/
+website/docs-pre-processed/
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -58,7 +58,4 @@ face temporary or permanent repercussions as determined by other members of the
 
 ## Attribution
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
-
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.4, available at [http://contributor-covenant.org/version/1/4](http://contributor-covenant.org/version/1/4/)
diff --git a/Makefile b/Makefile
@@ -200,16 +200,21 @@ else
 	@echo >&2 "No bzr binary found."; exit 1
 endif
 
+.PHONY: web-pre-process
+web-pre-process:
+	@echo ">> running documentation website pre processing"
+	@bash scripts/websitepreprocess.sh
+
 .PHONY: web
-web: $(HUGO)
+web: web-pre-process $(HUGO)
 	@echo ">> building documentation website"
 	# TODO(bwplotka): Make it --gc
-	@HUGO_ENV=production $(HUGO) --config $(WEB_DIR)/hugo.yaml --minify -v
+	@cd $(WEB_DIR) && HUGO_ENV=production $(HUGO) --config hugo.yaml --minify -v
 
 .PHONY: web-serve
-web-serve: $(HUGO)
+web-serve: web-pre-process $(HUGO)
 	@echo ">> serving documentation website"
-	@$(HUGO) --config $(WEB_DIR)/hugo.yaml -v server
+	@cd $(WEB_DIR) && $(HUGO) --config hugo.yaml -v server
 
 .PHONY: web-deploy
 web-deploy:

diff --git a/docs/components/bucket.md b/docs/components/bucket.md
@@ -1,7 +1,7 @@
 ---
 title: Bucket
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Bucket

diff --git a/docs/components/compact.md b/docs/components/compact.md
@@ -1,7 +1,7 @@
 ---
 title: Compact
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Compact

diff --git a/docs/components/query.md b/docs/components/query.md
@@ -1,7 +1,7 @@
 ---
 title: Query
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Query

diff --git a/docs/components/rule.md b/docs/components/rule.md
@@ -1,7 +1,7 @@
 ---
 title: Rule
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Rule

diff --git a/docs/components/sidecar.md b/docs/components/sidecar.md
@@ -1,7 +1,7 @@
 ---
 title: Sidecar
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Sidecar

diff --git a/docs/components/store.md b/docs/components/store.md
@@ -1,7 +1,7 @@
 ---
 title: Store
 type: docs
-menu: "components"
+menu: components
 ---
 
 # Store

diff --git a/docs/help/contribute.md → docs/contributing/dev.md b/docs/help/contribute.md → docs/contributing/dev.md
@@ -1,7 +1,7 @@
 ---
 title: Troubleshooting for dev workflow
 type: doc
-menu: help
+menu: contributing
 ---
 
 ## Dep `grouped write of manifest, lock and vendor: scratch directory ... already exists, please remove it`

diff --git a/docs/contributing/how-to-contribute-to-docs.md b/docs/contributing/how-to-contribute-to-docs.md
@@ -0,0 +1,64 @@
+---
+title: Contribute to docs
+type: docs
+menu: contributing
+---
+
+# How to contribute to Docs/Website
+
+`./docs` directory is used as markdown source files using [blackfriday](https://github.com/russross/blackfriday) to render Thanos website resources.
+
+However the aim for those is to also have those `*.md` files renderable and useable (including links) via GitHub.
+
+To make that happen we use following rules and helpers that are listed here
+
+## Font Matter
+
+[Font Matter](https://gohugo.io/content-management/front-matter/) is essential on top of every md file if 
+you want to link this file into any menu/submenu option. We use YAML formatting. This will render
+in GitHub as markdown just fine:
+
+```md
+
+---
+title: <titke>
+type: ...
+weight: <weight>
+menu: <where to link files in>  # This also is refered in permalinks.
+---
+
+```
+
+## Links
+
+Aim is to match linking behaviour in website being THE SAME as Github. This means:
+
+* For files in Hugo <content> dir (so `./docs`). Put `slug: /<filename with extension>`
+* For any sub dir add to `website/hugo.yaml` new dir as key  `permalinks:` with `<dir>: /<dir>/:filname.md`
+
+Then everywhere use native markdown *relative* symbolic links if you want to reference some md file from `docs`:
+
+`[title]( relative path to .md file )`
+
+Or absolute path to the project repo if you want to link to exact commit e.g:
+
+`[title]( /Makefile )`
+
+Small [post processing script](/scripts/websitepreprocess.sh) adjusts link for Hugo rendering.
+
+NOTE: Spaces matters so: `[xxx]( link` and `[xxx] (link` will not work.
+
+Why?
+
+* Links works on GitHub
+* Links works on website
+* Markdown plugins works as expected (e.g IDE integrations)
+* We use liche to test links.
+
+## Sections/Menu
+
+New menus `.Site.Menus` are added as soon as some file has Font Matter with certain `menu`.
+
+Keep `menu` the same as subdirectory the file is in. This will help to manage all docs.
+
+Show new menu section in main page by changing `website/layouts/_default/baseof.html` file.
diff --git a/docs/intro/design.md → docs/design.md b/docs/intro/design.md → docs/design.md
@@ -1,7 +1,8 @@
 ---
 title: Design
 type: docs
-menu: "thanos"
+menu: thanos
+slug: /design.md
 ---
 
 # Design

diff --git a/docs/intro/getting-started.md → docs/getting-started.md b/docs/intro/getting-started.md → docs/getting-started.md
@@ -1,22 +1,23 @@
 ---
 title: Getting Started
 type: docs
-menu: "thanos"
+menu: thanos
 weight: 1
+slug: /getting-started.md
 ---
 
 # Getting started
 
 Thanos provides a global query view, data backup, and historical data access as its core features in a single binary. All three features can be run independently of each other. This allows you to have a subset of Thanos features ready for immediate benefit or testing, while also making it flexible for gradual roll outs in more complex environments. 
 
 In this quick-start guide, we will configure Thanos and all components mentioned to work against a Google Cloud Storage bucket.
-At the moment, Thanos is able to use [different storage providers](/thanos/intro/storage), with the ability to add more providers as necessary.
+At the moment, Thanos is able to use [different storage providers](storage.md), with the ability to add more providers as necessary.
 
-Thanos will work in cloud native environments as well as more traditional ones. Some users run Thanos in Kubernetes while others on bare metal. More deployments examples and stories are described [here.]({{< ref "help/deployment-stories" >}})
+Thanos will work in cloud native environments as well as more traditional ones. Some users run Thanos in Kubernetes while others on bare metal. More deployments examples and stories will be described soon.
 
 ## Architecture Overview
 
-<img src="../img/arch.jpg" class="img-fluid" alt="architecture overview" />
+<img src="img/arch.jpg" class="img-fluid" alt="architecture overview" />
 
 ## Requirements
 
@@ -63,7 +64,7 @@ Thanos bases itself on vanilla [Prometheus](https://prometheus.io/) (v2.2.1+).
 
 Here's the Prometheus' versions Thanos is tested against:
 
-{{< embedcode file="/Makefile" lang="Makefile" start="44" lines="2" >}}
+[Makefile](/Makefile#35)
 
 ## Components
 
@@ -76,7 +77,7 @@ Following the KISS and Unix philosophies, Thanos is made of a set of components
 * Ruler: evaluates recording and alerting rules against data in Thanos for exposition and/or upload
 * Query Gateway: implements Prometheus' v1 API to aggregate data from the underlying components
 
-### [Sidecar]({{< ref "components/sidecar.md" >}})
+### [Sidecar](components/sidecar.md)
 
 Thanos integrates with existing Prometheus servers through a [Sidecar process](https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar#solution), which runs on the same machine or in the same pod as the Prometheus server. 
 
@@ -95,15 +96,15 @@ thanos sidecar \
     --objstore.config-file bucket_config.yaml \       # Storage configuration for uploading data
 ```
 
-The format of YAML file depends on the provider you choose. Examples of config and up-to-date list of storage types Thanos supports is available [here]({{< ref "intro/storage.md" >}}).
+The format of YAML file depends on the provider you choose. Examples of config and up-to-date list of storage types Thanos supports is available [here](storage.md).
 
 Rolling this out has little to zero impact on the running Prometheus instance. It is a good start to ensure you are backing up your data while figuring out the other pieces of Thanos.
 
 If you are not interested in backing up any data, the `--objstore.config-file` flag can simply be omitted.
 
 * _[Example Kubernetes manifest](https://github.com/improbable-eng/thanos/tree/master/tutorials/kubernetes-demo/manifests/prometheus-ha-sidecar.yaml)_
 * _[Example Kubernetes manifest with Minio upload](https://github.com/improbable-eng/thanos/tree/master/tutorials/kubernetes-demo/manifests/prometheus-ha-sidecar-lts.yaml)_
-* _[Details & Config for other object stores]({{< ref "intro/storage.md" >}})_
+* _[Details & Config for other object stores](storage.md)_
 
 #### Store API
 
@@ -137,9 +138,9 @@ global:
     replica: A
 ```
 
-### [Query Gateway]({{< ref "components/query.md" >}})
+### [Query Gateway](components/query.md)
 
-Now that we have setup the Sidecar for one or more Prometheus instances, we want to use Thanos' global [Query Layer]({{< ref "components/query.md" >}}) to evaluate PromQL queries against all instances at once.
+Now that we have setup the Sidecar for one or more Prometheus instances, we want to use Thanos' global [Query Layer](components/query.md) to evaluate PromQL queries against all instances at once.
 
 The Query component is stateless and horizontally scalable and can be deployed with any number of replicas. Once connected to the Sidecars, it automatically detects which Prometheus servers need to be contacted for a given PromQL query.
 
@@ -159,7 +160,7 @@ Go to the configured HTTP address that should now show a UI similar to that of P
 
 #### Deduplicating Data from Prometheus HA pairs
 
-The Query component is also capable of deduplicating data collected from Prometheus HA pairs. This requires configuring Prometheus's `global.external_labels` configuration block (as mentioned in the [External Labels section](#external-labels)) to identify the role of a given Prometheus instance.
+The Query component is also capable of deduplicating data collected from Prometheus HA pairs. This requires configuring Prometheus's `global.external_labels` configuration block (as mentioned in the [External Labels section](getting-started.md#external-labels)) to identify the role of a given Prometheus instance.
 
 A typical choice is simply the label name "replica" while letting the value be whatever you wish. For example, you might set up the following in Prometheus's configuration file:
 
@@ -205,12 +206,12 @@ thanos query \
     --store        dns+rest.thanos.peers:19092  # Use DNS lookup for getting all registered IPs as separate StoreAPIs    
 ```
 
-Read more details [here.]({{< ref "intro/service-discovery.md" >}})
+Read more details [here](service-discovery.md).
 
 * _[Example Kubernetes manifest](https://github.com/improbable-eng/thanos/tree/master/tutorials/kubernetes-demo/manifests/prometheus-ha-sidecar.yaml)_
 * _[Example Kubernetes manifest with GCS upload](https://github.com/improbable-eng/thanos/tree/master/tutorials/kubernetes-demo/manifests/prometheus-ha-sidecar-lts.yaml)_
 
-### [Store Gateway]({{< ref "components/store.md" >}})
+### [Store Gateway](components/store.md)
 
 As the sidecar backs up data into the object storage of your choice, you can decrease Prometheus retention and store less locally. However we need a way to query all that historical data again.
 The store gateway does just that by implementing the same gRPC data API as the sidecars but backing it with data it can find in your object storage bucket.
@@ -228,7 +229,7 @@ The store gateway occupies small amounts of disk space for caching basic informa
 
 * _[Example Kubernetes manifest](https://github.com/improbable-eng/thanos/tree/master/tutorials/kubernetes-demo/manifests/thanos-store-gateway.yaml)_
 
-### [Compactor]({{< ref "components/compact.md" >}})
+### [Compactor](components/compact.md)
 
 A local Prometheus installation periodically compacts older data to improve query efficiency. Since the sidecar backs up data as soon as possible, we need a way to apply the same process to data in the object storage.
 
@@ -245,12 +246,12 @@ The compactor is not in the critical path of querying or data backup. It can eit
 
 _NOTE: The compactor must be run as a **singleton** and must not run when manually modifying data in the bucket._
 
-### [Ruler]({{< ref "components/rule.md" >}})
+### [Ruler](components/rule.md)
 
 In case of Prometheus with Thanos sidecar does not have enough retention, or if you want to have alerts or recording rules that requires global view, Thanos has just the component for that: the [Ruler]({{< ref "components/rule.md" >}}),
 which does rule and alert evaluation on top of a given Thanos Querier.
 
-### [Receiver]({{< ref "components/rule.md" >}})
+### Receiver
 
 TBD
 

diff --git a/docs/help/common-issues.md b/docs/help/common-issues.md
diff --git a/docs/help/deployment-stories.md b/docs/help/deployment-stories.md
diff --git a/docs/intro/img/arch.jpg → docs/img/arch.jpg b/docs/intro/img/arch.jpg → docs/img/arch.jpg
diff --git a/docs/proposals/approved/201809_gossip-removal.md b/docs/proposals/approved/201809_gossip-removal.md
@@ -57,7 +57,7 @@ are too.. static. (: We need [File SD](https://github.com/improbable-eng/thanos/
 * Add File Service Discovery (SD): https://github.com/improbable-eng/thanos/issues/492
 * Remove gossip from the documentation, be clear what talks with what (!)
 * Deprecate gossip in code.
-* Remove gossip code and flags AFTER [File SD](https://github.com/improbable-eng/thanos/issues/492 is done and stable.
+* Remove gossip code and flags AFTER [File SD](https://github.com/improbable-eng/thanos/issues/492) is done and stable.
 
 ### Backwards compatibility
 

diff --git a/docs/intro/release-process.md → docs/release-process.md b/docs/intro/release-process.md → docs/release-process.md
@@ -1,4 +1,4 @@
-# Releases
+# For maintainers: Releases
 
 This page describes the release process for Thanos project.
 

diff --git a/docs/intro/service-discovery.md → docs/service-discovery.md b/docs/intro/service-discovery.md → docs/service-discovery.md
@@ -1,7 +1,8 @@
 ---
 title: Service Discovery
 type: docs
-menu: "thanos"
+menu: thanos
+slug: /service-discovery.md
 ---
 
 # Service Discovery

diff --git a/docs/intro/storage.md → docs/storage.md b/docs/intro/storage.md → docs/storage.md
@@ -1,8 +1,8 @@
 ---
 title: Object Storage
 type: docs
-menu: "thanos"
-markup: mmark
+menu: thanos
+slug: /storage.md
 ---
 
 # Object Storage