Refactor doc directories

Signed-off-by: Patrick East <east.patrick@gmail.com>

docs/Makefile

@@ -1,12 +1,12 @@
 .PHONY: clean
 clean:
-	rm -rf generated
-	rm -rf public
-	rm -rf resources
+	rm -rf $(CURDIR)/website/generated 
+	rm -rf $(CURDIR)/website/public 
+	rm -rf $(CURDIR)/website/esources
 
 .PHONY: generate
 generate:
-	scripts/load-docs.sh
+	$(CURDIR)/website/scripts/load-docs.sh
 
 .PHONY: setup
 setup:
@@ -16,6 +16,7 @@ setup:
 hugo-serve:
 	hugo \
 		server \
+		--source $(CURDIR)/website \
 		--contentDir generated \
 		--buildDrafts \
 		--buildFuture
@@ -24,19 +25,21 @@ hugo-serve:
 serve:
 	# must be run from root of repo for
 	# the netlify.toml config to work
-	cd .. && netlify dev --offline
+	cd $(CURDIR)/.. && netlify dev --offline
 
 .PHONY: docker-serve
 docker-serve:
 	docker run --rm -it \
-		-v $(PWD):/src \
+		-v $(CURDIR)/:/src \
 		-p 1313:1313 \
 		klakegg/hugo:0.53-ext server \
-			--contentDir /src/generated
+			--source /src/website \
+			--contentDir generated
 
 .PHONY: production-build
 production-build: clean generate
 	hugo \
+		--source $(CURDIR)/website \
 		--contentDir generated \
 		--ignoreCache \
 		--minify
@@ -44,6 +47,7 @@ production-build: clean generate
 .PHONY: preview-build
 preview-build: clean generate
 	hugo \
+		--source $(CURDIR)/website \
 		--contentDir generated \
 		--baseURL $(DEPLOY_PRIME_URL) \
 		--buildDrafts \
@@ -54,6 +58,7 @@ preview-build: clean generate
 .PHONY: linkcheck-build
 linkcheck-build:
 	hugo \
+		--source $(CURDIR)/website \
 		--contentDir generated \
 		--baseURL "/" \
 		--buildDrafts \

docs/README.md

@@ -1,15 +1,18 @@
 # The OPA Website and Documentation
+The content and tooling is separated into a few places:
 
-This directory contains all of the Markdown, HTML, Sass/CSS, and other assets needed
-to build the [openpolicyagent.org](https://openpolicyagent.org) website. See the
-section below for steps to build the site and test documentation changes
-locally.
+[devel/](./devel/) - Developer documentation for OPA (not part of the website)
 
-The raw OPA documentation can be found under the [content/docs](./content/docs)
-directory.
 
-> ### Developing OPA
-> For documentation on developing OPA, see the [devel](./devel) directory.
+[website/](./website/) - This directory contains all of the Markdown, HTML, Sass/CSS,
+and other assets needed to build the [openpolicyagent.org](https://openpolicyagent.org)
+website. See the section below for steps to build the site and test documentation changes
+locally. This content is not versioned for each release, it is common scaffolding for
+the website.
+
+[content/](./content/) - The raw OPA documentation can be found under the 
+directory. This content is versioned for each release and should have all images
+and code snippets alongside the markdown content files.
 
 ## Run the site locally
 
@@ -27,10 +30,13 @@ To generate them run:
 ```shell
 make generate
 ```
-The content then will be placed into `docs/generated/docs/$VERSION/`.
+The content then will be placed into `docs/website/generated/docs/$VERSION/`.
 
 ### Run the site locally using Docker
 
+> Note: running with docker only uses the Hugo server and not Netlify locally.
+This means that redirects and other Netlify features the site relies on will not work.
+
 If [Docker is running](https://docs.docker.com/get-started/):
 
 ```bash

docs/website/scripts/load-docs.sh

@@ -2,8 +2,6 @@
 
 set -xe
 
-RELEASES=$(cat RELEASES)
-
 ORIGINAL_COMMIT=$(git name-rev --name-only HEAD)
 # If no name can be found "git name-rev" returns
 # "undefined", in which case we'll just use the
@@ -13,9 +11,11 @@ if [[ "${ORIGINAL_COMMIT}" == "undefined" ]]; then
 fi
 
 ROOT_DIR=$(git rev-parse --show-toplevel)
-RELEASES_YAML_FILE=${ROOT_DIR}/docs/data/releases.yaml
+RELEASES_YAML_FILE=${ROOT_DIR}/docs/website/data/releases.yaml
 GIT_VERSION=$(git --version)
 
+RELEASES=$(cat ${ROOT_DIR}/docs/website/RELEASES)
+
 echo "Git version: ${GIT_VERSION}"
 
 echo "Saving current workspace state"
@@ -49,13 +49,13 @@ function cleanup {
 trap cleanup EXIT
 
 echo "Cleaning generated folder"
-rm -rf ${ROOT_DIR}/docs/generated/*
+rm -rf ${ROOT_DIR}/docs/website/generated/*
 
 echo "Removing data/releases.yaml file"
 rm -f ${RELEASES_YAML_FILE}
 
 for release in ${RELEASES}; do
-    version_docs_dir=${ROOT_DIR}/docs/generated/docs/${release}
+    version_docs_dir=${ROOT_DIR}/docs/website/generated/docs/${release}
 
     mkdir -p ${version_docs_dir}
 
@@ -75,6 +75,7 @@ for release in ${RELEASES}; do
     # if we were able to check out the version, otherwise skip it..
     if [[ "${errc}" == "0" ]]; then
         echo "Adding ${release} to releases.yaml"
+        mkdir -p $(dirname ${RELEASES_YAML_FILE})
         echo "- ${release}" >> ${RELEASES_YAML_FILE}
     else
         echo "WARNING: Failed to check out version ${version}!!"
@@ -102,4 +103,4 @@ echo "- edge" >> ${RELEASES_YAML_FILE}
 
 # Link instead of copy so we don't need to re-generate each time.
 # Use a relative link so it works in a container more easily.
-ln -s ../../content ${ROOT_DIR}/docs/generated/docs/edge
+ln -s ../../../content ${ROOT_DIR}/docs/website/generated/docs/edge