Update docs dev readme and netlify dev configuration

There are a few drawbacks to different dev approaches with modifying
and testing the website and docs content. This updates the makefile
to include a handful of options and info about when to use them.

This also changes to not use a “live” Hugo service behind netlify when
we run it locally in dev mode. This allows for the local netlify
preview to more accurately reflect the “real” build.

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

docs/Makefile

@@ -22,7 +22,7 @@ hugo-serve:
 		--buildFuture
 
 .PHONY: serve
-serve:
+serve: production-build
 	# must be run from root of repo for
 	# the netlify.toml config to work
 	cd $(CURDIR)/.. && netlify dev --offline

docs/README.md

@@ -14,6 +14,72 @@ the website.
 directory. This content is versioned for each release and should have all images
 and code snippets alongside the markdown content files.
 
+## Website Components
+
+The website ([openpolicyagent.org](https://openpolicyagent.org)) and doc's hosted there
+([openpolicyagent.org/docs](https://openpolicyagent.org/docs)) have a few components
+involved with the buildings and hosting.
+
+The static site is generated with [Hugo](https://gohugo.io/) which uses the markdown
+in [content/](./content) as its content for pages under `/docs/*`. There is a script
+to generate the previous supported versions, automated via `make generate`, and the
+latest (current working tree) documentations is under `/docs/edge/*`.
+
+The static site content is then hosted by [Netlify](https://www.netlify.com/). To
+support backwards compatible URLs (from pre-netlify days) and to have the `latest`
+version of the docs URLs work
+[openpolicyagent.org/docs/latest](https://openpolicyagent.org/docs/latest) the site
+relies on Netlify URL [redirects and rewrites](https://www.netlify.com/docs/redirects/)
+which are defined in [website/layouts/index.redirects](./webiste/layouts/index.redirects)
+and are build into a `_redirects` file when the Hugo build happens via
+`make production-build` or `make preview-build`.
+
+### How to Edit and Test
+
+Because of the different components at play there are a few different ways to
+test/view the website. The choice depends largely on what is being modified:
+
+#### Full Site Preview
+
+Go to [Netlify](https://www.netlify.com/) and log-in. Link to your public fork of
+OPA on github and have it deploy a site. As long as it is public this is free
+and can be configured to deploy test branches before opening PR's on the official
+OPA github repo.
+
+This approach gives the best simulation for what the website will behave like once
+code has merged.
+
+
+#### Modifying `content` (*.md)
+
+The majorify of this can be done with any markdown renderer (typically built-in or
+a plug-in for IDE's). The rendered output will be very similar to what Hugo will
+generate.
+ 
+> This excludes the Hugo shortcodes (places with `{{< SHORT_CODE >}}` in the markdown.
+  To see the output of these you'll need to involve Hugo
+
+#### Modifying the Hugo templates and/or website (HTML/CSS/JS)
+
+The easiest way is to run Hugo locally in dev mode. Changes made will be reflected
+immediately be the Hugo dev server. See 
+[Run the site locally using Docker](#run-the-site-locally-using-docker)
+
+> This approach will *not* include the Netlify redirects so urls like
+ `http://localhost:1313/docs/latest/` will not work. You must navigate directly to
+ the version of docs you want to test. Typically this will be
+ [http://localhost:1313/docs/edge/](http://localhost:1313/docs/edge/).
+
+
+#### Modifying the netlify config/redirects
+
+This requires either using the [Full Site Preview](#full-site-preview) or using
+the local dev tools as described below in:
+[Run the site locally without Docker](#run-the-site-locally-without-docker)
+
+The local dev tools will *not* give live updates as the content changes, but
+will give the most accurate production simulation.
+
 ## Run the site locally
 
 You can run the site locally [with Docker](#run-the-site-locally-using-docker) or

netlify.toml

@@ -12,10 +12,11 @@ command = "make docs-preview-build"
 command = "make docs-preview-build"
 
 [dev]
-# "netlify dev" will start the hugo dev server and act as a proxy
+# "netlify dev" will serve the static content using netlify locally
 # with all the redirects and other netlify specific rules in place.
-# NOTE: The command is from the root of the repo, not
-# the "base" directory.
-command = "make docs-hugo-serve"
 publish = "docs/website/public"
-port = 1313
+
+# To run the netlify dev service with hugo dev server "live" behind 
+# it uncomment these lines:
+#command = "make docs-hugo-serve"
+#port = 1313