Docs: Add minimal hugo build, update docs README (#20905)

* initial commit * remove menu and submenu * improve layout templates, improve README * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * fix typo * remove layouts * update readme, makefile * update docs command * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com> * Update docs/README.md Co-Authored-By: Diana Payton <52059945+oddlittlebird@users.noreply.github.com>
6 years ago · e5695b155b
parent 096b82027c
commit e5695b155b
10 changed files with 23 additions and 226 deletions
--- a/docs/.gitignore
+++ b/docs/.gitignore
@ -0,0 +1 @@
+data/menu.yaml
--- a/docs/Dockerfile
+++ b/docs/Dockerfile
@ -1,14 +0,0 @@
-FROM grafana/docs-base:latest
-
-# to get the git info for this repo
-# COPY config.toml /site
-
-# RUN rm -rf /site/content/*
-
-# COPY ./sources /site/content/docs/
-
-COPY config.toml /site
-COPY awsconfig /site
-COPY versions.json /site/static/js
-
-VOLUME ["/site/content"]
--- a/docs/Makefile
+++ b/docs/Makefile
@ -1,38 +1,2 @@
-.PHONY: all default docs docs-build docs-shell shell checkvars
-
-# to allow `make DOCSPORT=9000 docs`
-DOCSPORT := 3004
-
-DOCKER_DOCS_IMAGE := grafana/grafana-docs
-SOURCES_HOST_DIR := "$(shell pwd)/sources"
-
-# assuming grafana and grafana.org-repo to be checked out in the same folder
-DEFAULT_LAYOUTS_DIR := "$(shell pwd)/../../../../../../grafana.org/layouts"
-
-# to allow `make DOCSDIR=docs docs-shell` (to create a bind mount in docs)
-LAYOUTS_MOUNT := $(if $(LAYOUTS),-v $(DEFAULT_LAYOUTS_DIR):/site/layouts)
-DOCS_MOUNT := -v $(SOURCES_HOST_DIR):/site/content
-
-DOCKER_RUN_DOCS := docker run --rm -it $(DOCS_MOUNT) $(LAYOUTS_MOUNT) -e NOCACHE -p 3004:3004 -p 3005:3005
-
-VERSION := $(shell head -n 1 VERSION)
-
-default: docs
-
-checkvars:
-ifndef ENV
-	$(error ENV is undefined set via ENV=staging or ENV=prod as argument to make)
-endif
-
-docs: docs-build
-	$(DOCKER_RUN_DOCS) $(DOCS_MOUNT) -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" /bin/bash -c "grunt --env=dev-docs && grunt connect --port=3004"
-
-watch: docs-build
-	$(DOCKER_RUN_DOCS) $(DOCS_MOUNT) $(LAYOUTS_MOUNT) -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" /bin/bash -c "grunt --env=dev-docs && grunt connect --port=3004 & grunt watch --port=3004 --env=dev-docs"
-
-publish: checkvars docs-build
-	$(info Publishing ENV=${ENV} and VERSION=${VERSION})
-	$(DOCKER_RUN_DOCS) $(DOCS_MOUNT) -e DOCKERHOST "$(DOCKER_DOCS_IMAGE)" /bin/bash -c "./publish.sh ${ENV}-docs ${VERSION}"
-
-docs-build:
-	docker build -t "$(DOCKER_DOCS_IMAGE)" --no-cache .
+docs: 
+	docker run -v $(PWD)/sources:/hugo/content/docs/grafana/latest -p 3002:3002 --rm -it grafana/docs-base:latest
--- a/docs/README.md
+++ b/docs/README.md
@ -1,90 +1,38 @@
-### Note for external contributors
+# Building the docs locally

-We are currently working on migrating the docs to a new static website. The `grafana/website` repository will be private during this migration, which unfortunately means the docs site can't be built without access.
+When you contribute to documentation, it is a good practice to build the docs on your local machine to make sure your changes appear as you expect. This README explains the process for doing that.

-The Markdown content however, is still public in this repository. We still encourage pull requests to make the docs better, and we will make sure the changed content works well on the current docs site. Include any images in your pull request, and we will move them to the `grafana/website` repository.
+## Requirements

-# Building the docs
+Docker >= 2.1.0.3

-To build the docs locally, you need to have Docker installed. The docs are built using [Hugo](http://gohugo.io/) - a static site generator.
+## Build the doc site

-**Prepare the Docker image**:
+1. In the command line, make sure you are in the docs folder: `cd docs`.
+2. Run `make docs`. This launches a preview of the docs website at `http://localhost:3002/docs/grafana/latest/` which will refresh automatically when changes to content in the `sources` directory are made.

-> Due to migration to new static site, the Docker image needs to be built from `old-docs` branch.
+---

-Git clone `grafana/website` repo. Run these commands in the root of that repo. **Note** that you may require `sudo`
-when running `make docs-build` depending on how your system's Docker
-service is configured):
+## Content guidelines

-```
-git clone https://github.com/grafana/website
-cd website
-make docs-build
-```
+Edit content in the `sources` directory.

-**Build the Documentation**:
+### Using `relref` for internal links

-Now that the Docker image has been prepared we can build the
-grafana docs and start a docs server.
+Use the Hugo shortcode [relref](https://gohugo.io/content-management/cross-references/#use-ref-and-relref) anytime you are linking to other internal docs pages.

-If you have not cloned the Grafana repository already then:
+### Edit the side menu

-```
-cd ..
-git clone https://github.com/grafana/grafana
-```
+Edit [sources/menu.yaml](sources/menu.yaml) to make changes to the sidebar. Restart the `make run` command for changes to take effect.

-Switch your working directory to the directory this file
-(README.md) is in.
+### Add images

-```
-cd grafana/docs
-```
+Images are currently hosted in the grafana/website repo.

-An AWS config file is required to build the docs Docker image and to publish the site to AWS. If you are building locally only and do not have any AWS credentials for docs.grafana.org then create an empty file named `awsconfig` in the current directory.
+---

-```
-touch awsconfig
-```
+## Deploy changes to grafana.com

-Then run (possibly with `sudo`):
+When a PR is merged to master with changes in the `docs` directory, those changes are automatically synched to the grafana/website repo on the `docs-grafana` branch.

-```
-make watch
-```
-
-This command will not return control of the shell to the user. Instead
-the command is now running a new Docker container built from the image
-we created in the previous step.
-
-Open [localhost:3004](http://localhost:3004) to view the docs.
-
-### Images and Content
-
-All markdown files are part of [this repository](https://github.com/grafana/grafana). However, all images are added to the [website repository](https://github.com/grafana/website). Therefore, the process of adding images is not as straightforward. These are the steps:
-
-1. Ensure you create a feature branch within the [website repository](https://github.com/grafana/website) to make the change. This branch needs to be based on the `old-docs` branch.
-1. Ensure the image(s) are compressed and optimised e.g. Using [tinypng](https://tinypng.com/).
-1. Add the image(s) to the `/static/img/docs` directory.
-1. Then, make a commit that adds the image(s).
-1. The Pull Request you create needs to target where you branched off, the branch `old-docs`.
-
-Finally, run:
-
-```
-make docs-build
-```
-
-This will rebuild the docs Docker image.
-
-To be able to use your image(s) you have to quit (Ctrl+C) the `make watch` command (that you run in the same directory as this README). Then simply rerun `make watch`, it will restart the docs server but now with access to your image(s).
-
-### Editing content
-
-Changes to the markdown files should automatically cause a docs rebuild and live reload should reload the page in your browser.
-
-### Troubleshooting
-
-#### Running `make watch` errors out with `Warning: Task "default" not found.`
-
-Ensure that the Docker image from the [website repository](https://github.com/grafana/website) is built using the `old-docs` branch.
+In order to make those changes live, open a PR in the website repo that merges the `docs-grafana` branch into `master`. Then follow the publishing guidelines in that repo.
--- a/docs/config.toml
+++ b/docs/config.toml
@ -1,20 +0,0 @@
-
-baseurl = "http://localhost:3002/"
-languageCode = "en-us"
-title = "Grafana Documentation"
-canonifyurls = true
-relativeURLs = false
-verbose = true
-enableRobotsTXT = true
-disableSitemap = false
-disableRSS = false
-preservetaxonomynames = true
-metaDataFormat = "yaml"
-
-[taxonomies]
-tag = "tags"
-category = "categories"
-
-[permalinks]
-  blog = ":year/:month/:day/:title/"
-
--- a/docs/logo-horizontal.png
+++ b/docs/logo-horizontal.png
--- a/docs/logo-swirl.svg
+++ b/docs/logo-swirl.svg
@ -1,64 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!-- Generator: Adobe Illustrator 23.0.4, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
-<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
-	 viewBox="0 0 85.12 92.46" style="enable-background:new 0 0 85.12 92.46;" xml:space="preserve">
-<style type="text/css">
-	.st0{fill:url(#SVGID_1_);}
-</style>
-<linearGradient id="SVGID_1_" gradientUnits="userSpaceOnUse" x1="42.562" y1="113.2595" x2="42.562" y2="28.7828">
-	<stop  offset="0" style="stop-color:#FFF200"/>
-	<stop  offset="1" style="stop-color:#F15A29"/>
-</linearGradient>
-<path class="st0" d="M85.01,40.8c-0.14-1.55-0.41-3.35-0.93-5.32c-0.51-1.97-1.28-4.13-2.39-6.37c-1.12-2.24-2.57-4.57-4.47-6.82
-	c-0.74-0.88-1.54-1.76-2.42-2.6c1.3-5.17-1.59-9.65-1.59-9.65c-4.98-0.31-8.14,1.54-9.31,2.39c-0.2-0.08-0.39-0.17-0.59-0.25
-	c-0.85-0.34-1.72-0.66-2.61-0.95c-0.89-0.28-1.81-0.54-2.74-0.76c-0.94-0.22-1.89-0.4-2.86-0.55c-0.17-0.03-0.34-0.05-0.51-0.07
-	C52.41,2.9,46.18,0,46.18,0c-6.95,4.41-8.27,10.57-8.27,10.57s-0.03,0.14-0.07,0.36c-0.38,0.11-0.77,0.22-1.15,0.34
-	c-0.53,0.16-1.06,0.36-1.59,0.55c-0.53,0.21-1.06,0.41-1.58,0.64c-1.05,0.45-2.09,0.96-3.1,1.53c-0.99,0.55-1.95,1.16-2.9,1.82
-	c-0.14-0.06-0.24-0.11-0.24-0.11c-9.62-3.68-18.17,0.75-18.17,0.75c-0.78,10.24,3.84,16.68,4.76,17.86
-	c-0.23,0.63-0.44,1.27-0.64,1.92c-0.71,2.32-1.24,4.7-1.57,7.16c-0.05,0.35-0.09,0.71-0.13,1.07C2.63,48.84,0,57.84,0,57.84
-	c7.42,8.53,16.07,9.06,16.07,9.06c0.01-0.01,0.02-0.01,0.02-0.02c1.1,1.96,2.37,3.83,3.8,5.57c0.6,0.73,1.23,1.43,1.88,2.11
-	c-2.71,7.74,0.38,14.18,0.38,14.18c8.26,0.31,13.69-3.61,14.83-4.52c0.82,0.28,1.66,0.53,2.5,0.74c2.54,0.65,5.14,1.04,7.74,1.15
-	c0.65,0.03,1.3,0.04,1.95,0.04l0.31,0l0.21-0.01l0.41-0.01l0.4-0.02l0.01,0.01c3.89,5.55,10.74,6.34,10.74,6.34
-	c4.87-5.13,5.15-10.22,5.15-11.33l0,0c0,0,0-0.04,0-0.07c0-0.09,0-0.15,0-0.15s0,0,0,0c0-0.08-0.01-0.15-0.01-0.23
-	c1.02-0.72,2-1.49,2.92-2.31c1.95-1.76,3.65-3.77,5.06-5.93c0.13-0.2,0.26-0.41,0.39-0.62c5.51,0.32,9.39-3.41,9.39-3.41
-	c-0.91-5.74-4.18-8.54-4.87-9.07l0,0c0,0-0.03-0.02-0.07-0.05c-0.04-0.03-0.06-0.05-0.06-0.05l0,0c-0.04-0.02-0.08-0.05-0.12-0.08
-	c0.03-0.35,0.06-0.69,0.08-1.04c0.04-0.62,0.06-1.24,0.06-1.85l0-0.46l0-0.23l0-0.12c0-0.16,0-0.1,0-0.16l-0.02-0.38l-0.03-0.52
-	c-0.01-0.18-0.02-0.34-0.04-0.5c-0.01-0.16-0.03-0.32-0.05-0.48l-0.06-0.48l-0.07-0.47c-0.09-0.63-0.21-1.26-0.36-1.88
-	c-0.58-2.47-1.54-4.82-2.82-6.93c-1.28-2.11-2.86-3.98-4.65-5.56c-1.79-1.58-3.79-2.85-5.9-3.79c-2.1-0.95-4.31-1.55-6.51-1.83
-	c-1.1-0.14-2.2-0.2-3.28-0.19l-0.41,0.01l-0.1,0c-0.03,0-0.15,0-0.14,0l-0.17,0.01l-0.4,0.03c-0.15,0.01-0.31,0.02-0.45,0.04
-	c-0.56,0.05-1.11,0.13-1.66,0.23c-2.18,0.41-4.24,1.2-6.06,2.28c-1.82,1.09-3.39,2.45-4.68,3.98c-1.28,1.54-2.28,3.24-2.96,5
-	c-0.69,1.76-1.07,3.58-1.18,5.35c-0.03,0.44-0.04,0.88-0.03,1.32c0,0.11,0,0.22,0.01,0.33l0.01,0.35c0.02,0.21,0.03,0.42,0.05,0.63
-	c0.09,0.9,0.25,1.75,0.49,2.58c0.48,1.66,1.25,3.15,2.2,4.43c0.95,1.28,2.08,2.33,3.28,3.15c1.2,0.82,2.49,1.41,3.76,1.79
-	c1.27,0.38,2.54,0.54,3.74,0.53c0.15,0,0.3,0,0.44-0.01c0.08,0,0.16-0.01,0.24-0.01c0.08,0,0.16-0.01,0.24-0.01
-	c0.13-0.01,0.25-0.03,0.38-0.04c0.03,0,0.07-0.01,0.11-0.01l0.12-0.02c0.08-0.01,0.15-0.02,0.23-0.03c0.16-0.02,0.29-0.05,0.43-0.08
-	c0.14-0.03,0.28-0.05,0.42-0.09c0.27-0.06,0.54-0.14,0.8-0.22c0.52-0.17,1.01-0.38,1.46-0.61c0.45-0.23,0.87-0.5,1.26-0.77
-	c0.11-0.08,0.22-0.16,0.33-0.25c0.42-0.33,0.48-0.94,0.15-1.35c-0.29-0.36-0.79-0.45-1.19-0.23c-0.1,0.05-0.2,0.11-0.3,0.16
-	c-0.35,0.17-0.71,0.32-1.09,0.45c-0.39,0.12-0.79,0.22-1.2,0.29c-0.21,0.03-0.42,0.06-0.63,0.08c-0.11,0.01-0.21,0.02-0.32,0.02
-	c-0.11,0-0.22,0.01-0.32,0.01c-0.1,0-0.21,0-0.31-0.01c-0.13-0.01-0.26-0.01-0.39-0.02c0,0-0.07,0-0.01,0l-0.04,0L51.4,61.6
-	c-0.06-0.01-0.12-0.01-0.17-0.02c-0.12-0.01-0.23-0.03-0.35-0.04c-0.93-0.13-1.88-0.4-2.79-0.82c-0.91-0.41-1.79-0.98-2.57-1.69
-	c-0.79-0.71-1.48-1.56-2.01-2.52c-0.54-0.96-0.92-2.03-1.09-3.16c-0.09-0.56-0.13-1.14-0.11-1.71c0.01-0.16,0.01-0.31,0.02-0.47
-	c0,0.04,0-0.02,0-0.03l0-0.06l0.01-0.12c0.01-0.08,0.01-0.15,0.02-0.23c0.03-0.31,0.08-0.62,0.13-0.92
-	c0.43-2.45,1.65-4.83,3.55-6.65c0.47-0.45,0.98-0.87,1.53-1.25c0.55-0.37,1.12-0.7,1.73-0.98c0.6-0.28,1.23-0.5,1.88-0.68
-	c0.65-0.17,1.31-0.29,1.98-0.35c0.34-0.03,0.67-0.04,1.01-0.04c0.09,0,0.16,0,0.23,0l0.27,0.01l0.17,0.01c0.07,0,0,0,0.03,0l0.07,0
-	l0.27,0.02c0.73,0.06,1.46,0.16,2.17,0.32c1.43,0.32,2.83,0.85,4.13,1.57c2.6,1.44,4.81,3.69,6.17,6.4c0.69,1.35,1.16,2.81,1.4,4.31
-	c0.06,0.38,0.1,0.76,0.13,1.14l0.02,0.29l0.01,0.29c0.01,0.1,0.01,0.19,0.01,0.29c0,0.09,0.01,0.2,0,0.27l0,0.25l-0.01,0.28
-	c-0.01,0.19-0.02,0.49-0.03,0.67c-0.03,0.42-0.07,0.83-0.12,1.24c-0.05,0.41-0.12,0.82-0.19,1.22c-0.08,0.4-0.17,0.81-0.27,1.21
-	c-0.2,0.8-0.46,1.59-0.76,2.36c-0.61,1.54-1.42,3-2.4,4.36c-1.96,2.7-4.64,4.9-7.69,6.29c-1.52,0.69-3.13,1.19-4.78,1.47
-	c-0.82,0.14-1.66,0.22-2.5,0.25l-0.15,0.01l-0.13,0l-0.27,0l-0.41,0l-0.21,0c0.11,0-0.02,0-0.01,0l-0.08,0
-	c-0.45-0.01-0.9-0.03-1.34-0.07c-1.79-0.13-3.55-0.45-5.27-0.95c-1.71-0.49-3.38-1.16-4.95-2c-3.14-1.68-5.95-3.98-8.15-6.76
-	c-1.11-1.38-2.07-2.87-2.87-4.43c-0.8-1.56-1.42-3.2-1.89-4.88c-0.46-1.68-0.75-3.39-0.86-5.12l-0.02-0.32l-0.01-0.08l0-0.07l0-0.14
-	l-0.01-0.28l0-0.07l0-0.1l0-0.2l-0.01-0.4l0-0.08c0,0.01,0,0.01,0-0.03l0-0.16c0-0.21,0.01-0.42,0.01-0.63
-	c0.03-0.85,0.1-1.73,0.21-2.61c0.11-0.88,0.26-1.76,0.44-2.63c0.18-0.87,0.39-1.74,0.64-2.59c0.49-1.71,1.1-3.36,1.82-4.92
-	c1.44-3.12,3.34-5.88,5.61-8.09c0.57-0.55,1.16-1.08,1.77-1.57c0.61-0.49,1.25-0.95,1.9-1.37c0.65-0.43,1.32-0.82,2.02-1.18
-	c0.34-0.19,0.7-0.35,1.05-0.52c0.18-0.08,0.36-0.16,0.53-0.24c0.18-0.08,0.36-0.16,0.54-0.23c0.72-0.3,1.46-0.56,2.21-0.8
-	c0.19-0.06,0.38-0.11,0.56-0.17c0.19-0.06,0.38-0.1,0.57-0.16c0.38-0.11,0.76-0.2,1.14-0.29c0.19-0.05,0.39-0.08,0.58-0.13
-	c0.19-0.04,0.38-0.08,0.58-0.12c0.19-0.04,0.39-0.07,0.58-0.11l0.29-0.05l0.29-0.04c0.2-0.03,0.39-0.06,0.59-0.09
-	c0.22-0.04,0.44-0.05,0.66-0.09c0.18-0.02,0.48-0.06,0.65-0.08c0.14-0.01,0.28-0.03,0.41-0.04l0.28-0.03l0.14-0.01l0.16-0.01
-	c0.22-0.01,0.44-0.03,0.66-0.04l0.33-0.02c0,0,0.12,0,0.02,0l0.07,0l0.14-0.01c0.19-0.01,0.38-0.02,0.56-0.03
-	c0.75-0.02,1.5-0.02,2.24,0c1.48,0.06,2.93,0.22,4.34,0.48c2.82,0.53,5.49,1.43,7.89,2.62c2.41,1.18,4.57,2.63,6.44,4.2
-	c0.12,0.1,0.23,0.2,0.35,0.3c0.11,0.1,0.23,0.2,0.34,0.3c0.23,0.2,0.44,0.41,0.66,0.61c0.22,0.2,0.43,0.41,0.64,0.62
-	c0.2,0.21,0.41,0.41,0.61,0.63c0.8,0.84,1.53,1.69,2.19,2.55c1.33,1.71,2.39,3.44,3.24,5.07c0.05,0.1,0.11,0.2,0.16,0.3
-	c0.05,0.1,0.1,0.2,0.15,0.3c0.1,0.2,0.2,0.4,0.29,0.6c0.09,0.2,0.19,0.39,0.27,0.59c0.09,0.2,0.17,0.39,0.25,0.58
-	c0.32,0.76,0.61,1.49,0.84,2.18c0.39,1.11,0.67,2.11,0.89,2.98c0.09,0.35,0.42,0.58,0.78,0.55c0.37-0.03,0.66-0.34,0.66-0.71
-	C85.14,43.15,85.11,42.05,85.01,40.8z"/>
-</svg>
--- a/docs/publish.sh
+++ b/docs/publish.sh
@ -1,3 +0,0 @@
-#!/bin/bash
-
-make publish ENV=prod VERSION=root
--- a/docs/s3_website.json
+++ b/docs/s3_website.json
@ -1,11 +0,0 @@
-{
-  "ErrorDocument": {
-    "Key": "jsearch/index.html"
-  },
-  "IndexDocument": {
-    "Suffix": "index.html"
-  },
-  "RoutingRules": [
-    { "Condition": { "KeyPrefixEquals": "jsearch/index.html" }, "Redirect": { "HostName": "$BUCKET", "ReplaceKeyPrefixWith": "jsearch/" } }
-  ]
-}
--- a/docs/yarn.lock
+++ b/docs/yarn.lock
@ -1,4 +0,0 @@
-# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
-# yarn lockfile v1
-
-