From 2d59147360e99279616fba4801683f32c89198e3 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 3 Sep 2024 17:01:05 +0100 Subject: [PATCH 1/5] Update documentation Makefile and README This commit updates the documentation Makefile and README, reflecting changes to it across NGINX's open source repositories for consistency. It removes unnecessary targets: Netlify is no longer used, nor was the Makefile used for Netlify for quite some time. The guidance for Makefile targets in the README is updated accordingly, as well formatting instructions for how we use Hugo contemporaneously. --- docs/Makefile | 50 +++++++++++++------------------------------------- docs/README.md | 45 ++++++++++++++++++++++----------------------- 2 files changed, 35 insertions(+), 60 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index b0d647edc4..6b980f1566 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,25 +1,20 @@ HUGO?=hugo -# the officially recommended unofficial docker image HUGO_IMG?=hugomods/hugo:0.115.3 THEME_MODULE = github.com/nginxinc/nginx-hugo-theme -## Pulls the current theme version from the Netlify settings THEME_VERSION = 0.41.14 -NETLIFY_DEPLOY_URL = ${DEPLOY_PRIME_URL} -# if there's no local hugo, fallback to docker 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 + HUGO=docker run --rm -it -v ${CURDIR}:/src -p 1313:1313 ${HUGO_IMG} hugo --bind 0.0.0.0 -p 1313 endif endif MARKDOWNLINT?=markdownlint MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest -# if there's no local markdownlint, fallback to docker ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) ifneq (, $(shell $(NETLIFY) "true")) @@ -32,60 +27,41 @@ endif MARKDOWNLINKCHECK?=markdown-link-check MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable -# if there's no local markdown-link-check, fallback to docker + ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) ifneq (, $(shell $(NETLIFY) "true")) $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) endif else - MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/site --workdir /site ${MARKDOWNLINKCHECK_IMG} + MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} 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 - -all-staging: hugo-mod build-staging - -all-dev: hugo-mod build-dev - -all-local: clean hugo-mod build-production +.PHONY: docs docs-draft docs-local clean hugo-get hugo-tidy lint-markdown link-check 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 -watch-drafts: +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.json -- content +clean: + [ -d "public" ] && rm -rf "public" -# Commands used by Netlify CI -hugo-mod: +hugo-get: hugo mod get $(THEME_MODULE)@v$(THEME_VERSION) hugo-tidy: hugo mod tidy -build-production: - hugo --gc -e production +hugo-update: hugo-get hugo-tidy -build-staging: - hugo --gc -e staging - -build-dev: - hugo --gc -e development +lint-markdown: + ${MARKDOWNLINT} -c .markdownlint.yaml -- content -deploy-preview: hugo-mod - hugo --gc -b ${NETLIFY_DEPLOY_URL}/nginx-ingress-controller/ +link-check: + ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 41b345b769..3b4a8f986e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,30 +30,29 @@ To work on documentation, create a feature branch in a forked repository then ta The documentation is published from the latest public release branch. If your changes require immediate publication, create a pull request to cherry-pick changes from `main` to the public release branch. -## Developing documentation locally +## Develop documentation locally -To build the documentation locally, run the `make` command inside this `/site/` directory: +To build the documentation locally, use the `make` command in the documentation folder with these targets: ```text -make docs - Builds the documentation set with the output as the '/public' directory -make clean - Removes the local '/public/' directory -make watch - Starts a local Hugo server for live previews -make watch-drafts - Starts a local Hugo server for live previews, including documentation marked with 'draft: true' -make link-check - Check for any broken links in the documentation -make lint-markdown - Runs markdownlint to identify possible markdown formatting issues +make docs - Builds the documentation +make watch - Runs a local Hugo server to automatically preview changes +make drafts - Runs a local Hugo server, and displays documentation marked as drafts +make clean - Removes the output 'public' directory created by Hugo +make hugo-get - Updates the go module file with the latest version of the theme +make hugo-tidy - Removes unnecessary dependencies from the go module file +make hugo-update - Runs the hugo-get and hugo-tidy targets in sequence +make lint-markdown - Runs markdownlint on the content folder +make link-check - Runs markdown-link-check on all Markdown files ``` -The `watch` options automatically reload the Hugo server, allowing you to view updates as you work. - -> **Note**: The documentation uses build environments to control the baseURL used for things like internal references and static resources. The configuration for each environment can be found in the `config` directory. When running Hugo you can specify the environment and baseURL, but it's unnecessary. - ## Adding new documentation -### Using Hugo to generate a new documentation file +### Generate a new documentation file using Hugo -To create a new documentation file with the pre-configured Hugo front-matter for the task template, run the following command inside this `/site` directory: +To create a new documentation file containing the pre-configured Hugo front-matter with the task template, **run the following command in the documentation directory**: -`hugo new /.md` +`hugo new /.` For example: @@ -61,19 +60,19 @@ For example: hugo new getting-started/install.md ``` -The default template (task) should be used for most pages. For other content templates, you can use the `--kind` flag: +The default template -- task -- should be used for most documentation. To create documentation using the other content templates, you can use the `--kind` flag: ```shell hugo new tutorials/deploy.md --kind tutorial ``` -The available content templates (`kind`) are: +The available content types (`kind`) are: -- concept: Help a user learn about a specific feature or feature set. -- tutorial: Walk a user through an example use case scenario. -- reference: Describes an API, command line tool, configuration options, etc. -- troubleshooting: Guide a user towards solving a specific problem. -- openapi: A template with the requirements to render an openapi.yaml specification. +- concept: Helps a customer learn about a specific feature or feature set. +- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment. +- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. +- troubleshooting: Helps a customer solve a specific problem. +- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec ## Documentation formatting @@ -119,7 +118,7 @@ Use the `img` [shortcode](#using-hugo-shortcodes) to add images into your docume ### Using Hugo shortcodes -[Hugo shortcodes](/docs/themes/f5-hugo/layouts/shortcodes/) are used to format callouts, add images, and reuse content across different pages. +[Hugo shortcodes](https://github.com/nginxinc/nginx-hugo-theme/tree/main/layouts/shortcodes) are used to format callouts, add images, and reuse content across different pages. For example, to use the `note` callout: From 98bf6b5e206c485d24beb8c26faffed90f757957 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 3 Sep 2024 16:04:20 +0000 Subject: [PATCH 2/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/Makefile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 6b980f1566..4a168074e7 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -50,7 +50,7 @@ drafts: ${HUGO} --bind 0.0.0.0 -p 1313 server -D --disableFastRender clean: - [ -d "public" ] && rm -rf "public" + [ -d "public" ] && rm -rf "public" hugo-get: hugo mod get $(THEME_MODULE)@v$(THEME_VERSION) @@ -64,4 +64,4 @@ lint-markdown: ${MARKDOWNLINT} -c .markdownlint.yaml -- content link-check: - ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') \ No newline at end of file + ${MARKDOWNLINKCHECK} $(shell find content -name '*.md') From 52332012f200841098662529cd64552a9bf26e22 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 3 Sep 2024 17:05:39 +0100 Subject: [PATCH 3/5] Revert template explanation changes --- docs/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/README.md b/docs/README.md index 3b4a8f986e..ef02a410bd 100644 --- a/docs/README.md +++ b/docs/README.md @@ -66,13 +66,13 @@ The default template -- task -- should be used for most documentation. To create hugo new tutorials/deploy.md --kind tutorial ``` -The available content types (`kind`) are: +The available content templates (`kind`) are: -- concept: Helps a customer learn about a specific feature or feature set. -- tutorial: Walks a customer through an example use case scenario; results in a functional PoC environment. +- concept: Help a user learn about a specific feature or feature set. +- tutorial: Walk a user through an example use case scenario; results in a functional PoC environment. - reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. -- troubleshooting: Helps a customer solve a specific problem. -- openapi: Contains front-matter and shortcode for rendering an openapi.yaml spec +- troubleshooting: Help a user solve a specific problem. +- openapi: A template with the requirements to render an openapi.yaml specification ## Documentation formatting From b0454f793d10ae8e6be21ce336d0e18b45117f2f Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Tue, 3 Sep 2024 17:08:44 +0100 Subject: [PATCH 4/5] Change template options again. --- docs/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/README.md b/docs/README.md index ef02a410bd..033f0033e1 100644 --- a/docs/README.md +++ b/docs/README.md @@ -69,10 +69,10 @@ hugo new tutorials/deploy.md --kind tutorial The available content templates (`kind`) are: - concept: Help a user learn about a specific feature or feature set. -- tutorial: Walk a user through an example use case scenario; results in a functional PoC environment. -- reference: Describes an API, command line tool, config options, etc.; should be generated automatically from source code. -- troubleshooting: Help a user solve a specific problem. -- openapi: A template with the requirements to render an openapi.yaml specification +- tutorial: Walk a user through an example use case scenario. +- reference: Describes an API, command line tool, configuration options, etc. +- troubleshooting: Guide a user towards solving a specific problem. +- openapi: A template with the requirements to render an openapi.yaml specification. ## Documentation formatting From dadbfcc3e15baa0ef307f8a9ec1986746c57c334 Mon Sep 17 00:00:00 2001 From: Alan Dooley Date: Wed, 4 Sep 2024 09:55:47 +0100 Subject: [PATCH 5/5] Apply suggestions from code review Signed-off-by: Alan Dooley --- docs/Makefile | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 4a168074e7..d46833e92a 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -17,7 +17,6 @@ MARKDOWNLINT_IMG?=ghcr.io/igorshubovych/markdownlint-cli:latest ifeq (, $(shell ${MARKDOWNLINT} version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) $(error Docker and markdownlint are not installed. markdownlint or Docker are required to lint.) endif else @@ -30,11 +29,10 @@ MARKDOWNLINKCHECK_IMG?=ghcr.io/tcort/markdown-link-check:stable ifeq (, $(shell ${MARKDOWNLINKCHECK} --version 2> /dev/null)) ifeq (, $(shell docker version 2> /dev/null)) -ifneq (, $(shell $(NETLIFY) "true")) $(error Docker and markdown-link-check are not installed. markdown-link-check or Docker are required to check links.) endif else - MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/docs --workdir /docs ${MARKDOWNLINKCHECK_IMG} + MARKDOWNLINKCHECK=docker run --rm -it -v ${CURDIR}:/site --workdir /site ${MARKDOWNLINKCHECK_IMG} endif endif