Update guidance and tooling for documentation (#1431)

These changes add a README file to the site subfolder instructing a reader on how to build and contribute to the documentation. It removes a similar README from the developer documentation folder while incorporating a number of improvements. With this commit there are also changes to the Makefile, with the aim of clarifying the intent and usage of certain commands. Finally, the new README references and is referenced by the general CONTRIBUTION guidelines to reflect the standardised processes and reinforce our "Docs like Code" approach. Co-authored-by: Saylor Berman <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
nginxinc · Jan 16, 2024 · 3cadadb · 3cadadb
1 parent a0b6293
commit 3cadadb
Show file tree

Hide file tree

Showing 4 changed files with 178 additions and 180 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -43,6 +43,7 @@ Follow our [Installation Instructions](https://docs.nginx.com/nginx-gateway-fabr
 - We use [Go Modules](https://github.com/golang/go/wiki/Modules) for managing dependencies.
 - We use [Ginkgo](https://onsi.github.io/ginkgo/) and [Gomega](https://onsi.github.io/gomega/) for our BDD style unit
   tests.
+- The documentation website is found under `site/`.
 
 ## Contributing
 
@@ -93,6 +94,7 @@ Before beginning development, familiarize yourself with the following documents:
   conventions to follow when writing Go code for the project.
 - [Architecture](https://docs.nginx.com/nginx-gateway-fabric/overview/gateway-architecture/): A high-level overview of the project's architecture.
 - [Design Principles](/docs/developer/design-principles.md): An overview of the project's design principles.
+- [NGINX Gateway Fabric Documentation](/site/README.md): An explanation of the documentation tooling and conventions.
 
 ## Contributor License Agreement
 

diff --git a/docs/developer/documentation.md b/docs/developer/documentation.md
diff --git a/site/Makefile b/site/Makefile
@@ -12,7 +12,7 @@ ifeq (, $(shell ${HUGO} version 2> /dev/null))
 ifeq (, $(shell docker version 2> /dev/null))
     $(error Docker and Hugo are not installed. Hugo (<0.91) or Docker are required to build the local preview.)
 else
-    HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo --bind 0.0.0.0 -p 1313
+    HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo
 endif
 endif
 
@@ -43,7 +43,6 @@ else
 endif
 endif
 
-
 .PHONY: all all-staging all-dev all-local clean hugo-mod build-production build-staging build-dev docs-drafts docs deploy-preview
 
 all: hugo-mod build-production
@@ -54,28 +53,25 @@ all-dev: hugo-mod build-dev
 
 all-local: clean hugo-mod build-production
 
-# Removes the public directory generated by the `hugo` command
+docs:
+	${HUGO}
+
 clean:
 	if [[ -d ${PWD}/public ]] ; then rm -rf ${PWD}/public && echo "Removed public directory" ; else echo "Did not find a public directory to remove" ; fi
 
+watch:
+	${HUGO} --bind 0.0.0.0 -p 1313 server --disableFastRender
 
-docs-drafts:
-	${HUGO} server -D --disableFastRender
-
-docs-local: clean
-	${HUGO}
-
-docs:
-	${HUGO} server --disableFastRender
-
-lint-markdown:
-	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
+watch-drafts:
+	${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender
 
 link-check:
 	${MARKDOWNLINKCHECK} $(shell find content -name '*.md')
 
+lint-markdown:
+	${MARKDOWNLINT} -c .markdownlint.yaml  -- content
 
-## commands for use in Netlify CI
+# Commands used by Netlify CI
 hugo-mod:
 	hugo mod get $(THEME_MODULE)@v$(THEME_VERSION)