Update documentation folder, dependencies and deployment action (ngin…

…x#6554)

This commit makes a number of changes related to documentation:

- It changes the folder from /docs to /site, matching other NGINX
  software, which retain /docs for development documentation
- It updates go.mod with the new theme file
- It updates the Docs section of the .gitignore file
- It updates the deployment action to match the folder change, and adds
  the ability to change the theme version during deployment

Notably, the latest theme update has a new shortcode which allows for
code files to be embedded from GitHub links, creating the possibility of
single sources of truth in documentation examples.

There are a number of other CI configuration changes that have also
been made to account for this update.

.fossa.yml

@@ -4,4 +4,4 @@ targets:
     - type: setuptools
 paths:
   exclude:
-    - docs
+    - site

.github/dependabot.yml

@@ -56,6 +56,6 @@ updates:
           - "patch"
 
   - package-ecosystem: gomod
-    directory: /docs
+    directory: /site
     schedule:
       interval: weekly

.github/scripts/release-notes-update.sh

@@ -6,7 +6,7 @@ ROOTDIR=$(git rev-parse --show-toplevel || echo ".")
 TMPDIR=/tmp
 DEBUG=${DEBUG:-"false"}
 
-DOCS_TO_UPDATE_FOLDER=${ROOTDIR}/docs/content
+DOCS_TO_UPDATE_FOLDER=${ROOTDIR}/site/content
 
  usage() {
     echo "Usage: $0 <ic_version> <helm_chart_version> <k8s_versions> <release_date>"

.github/scripts/release-version-update.sh

@@ -9,7 +9,7 @@ DEPLOYMENT_PATH="${ROOTDIR}/deployments"
 EXAMPLES_PATH="${ROOTDIR}/examples"
 DEBUG=${DEBUG:-"false"}
 
-DOCS_TO_UPDATE_FOLDER=${ROOTDIR}/docs/content
+DOCS_TO_UPDATE_FOLDER=${ROOTDIR}/site/content
 FILES_TO_UPDATE_IC_VERSION=(
     "${ROOTDIR}/.github/data/version.txt"
     "${ROOTDIR}/README.md"
@@ -121,9 +121,9 @@ for i in "${FILE_TO_UPDATE_HELM_CHART_VERSION[@]}"; do
 done
 
 # update docs with new versions
-echo -n "${new_ic_version}" > ./docs/layouts/shortcodes/nic-version.html
-echo -n "${new_helm_chart_version}" > ./docs/layouts/shortcodes/nic-helm-version.html
-echo -n "${new_operator_version}" > ./docs/layouts/shortcodes/nic-operator-version.html
+echo -n "${new_ic_version}" > ./site/layouts/shortcodes/nic-version.html
+echo -n "${new_helm_chart_version}" > ./site/layouts/shortcodes/nic-helm-version.html
+echo -n "${new_operator_version}" > ./site/layouts/shortcodes/nic-operator-version.html
 
 # update examples with new versions
 example_files=$(find "${EXAMPLES_PATH}" -type f -name "*.md")

.github/scripts/variables.sh

@@ -18,7 +18,7 @@ get_docker_md5() {
 }
 
 get_go_code_md5() {
-  find . -type f \( -name "*.go" -o -name go.mod -o -name go.sum -o -name "*.tmpl" -o -name "version.txt" \) -not -path "./docs*"  -exec md5sum {} + | LC_ALL=C sort  | md5sum | awk '{ print $1 }'
+  find . -type f \( -name "*.go" -o -name go.mod -o -name go.sum -o -name "*.tmpl" -o -name "version.txt" \) -not -path "./site*"  -exec md5sum {} + | LC_ALL=C sort  | md5sum | awk '{ print $1 }'
 }
 
 get_tests_md5() {

.github/workflows/ci.yml

@@ -60,8 +60,8 @@ jobs:
       - name: Filter only docs changes
         id: docs
         run: |
-          files=$(git diff --name-only HEAD^ | egrep -v "^docs/" | egrep -v "^examples/" | egrep -v "^README.md")
-          docs_files=$(git diff --name-only HEAD^ | grep "^docs/")
+          files=$(git diff --name-only HEAD^ | egrep -v "^site/" | egrep -v "^examples/" | egrep -v "^README.md")
+          docs_files=$(git diff --name-only HEAD^ | grep "^site/")
           if [ -z "$files" ]; then
             echo "docs_only=true" >> $GITHUB_OUTPUT
           else
@@ -206,7 +206,7 @@ jobs:
 
       - name: Check if make docs builds
         if: ${{ needs.checks.outputs.some_docs == 'true' }}
-        run: cd docs && make docs-ci
+        run: cd site && make docs-ci
 
   unit-tests:
     name: Unit Tests

.github/workflows/codeql-analysis.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Filter only docs changes
         id: docs
         run: |
-          files=$(git diff --name-only HEAD^ | egrep -v "^docs/" | egrep -v "^examples/" | egrep -v "^README.md")
+          files=$(git diff --name-only HEAD^ | egrep -v "^site/" | egrep -v "^examples/" | egrep -v "^README.md")
           if [ -z "$files" ]; then
             echo "docs_only=true" >> $GITHUB_OUTPUT
           else

.github/workflows/dependabot-hugo.yml

@@ -3,7 +3,7 @@ name: Run hugo commands on Dependabot PRs
 on:
   pull_request:
     paths:
-      - "docs/go.mod"
+      - "site/go.mod"
   merge_group:
 
 permissions:
@@ -38,7 +38,7 @@ jobs:
 
       - name: Run build
         if: ${{ steps.dependabot-metadata.outputs.package-ecosystem == 'go_modules' && contains(steps.dependabot-metadata.outputs.dependency-names, 'hugo') }}
-        working-directory: docs
+        working-directory: site
         run: |
           hugo mod tidy
           hugo mod verify

.github/workflows/docs-build-push.yml

@@ -12,11 +12,16 @@ on:
           - dev
           - staging
           - prod
+      hugo_theme_override:
+        description: 'Override hugo theme (leave blank to use latest version)'
+        required: false
+        default: ''
+        type: string
   pull_request:
     branches:
       - "*"
     paths:
-      - "docs/**"
+      - "site/**"
   push:
     branches:
       - "release-3.7"
@@ -34,9 +39,10 @@ jobs:
       production_url_path: "/nginx-ingress-controller"
       preview_url_path: "/previews/nginx-ingress-controller"
       docs_source_path: "public/nginx-ingress-controller"
-      docs_build_path: "./docs"
+      docs_build_path: "./site"
       doc_type: "hugo"
       environment: ${{ inputs.environment }}
+      force_hugo_theme_version: ${{inputs.hugo_theme_override}}
       auto_deploy_branch: "release-3.7"
       auto_deploy_env: "prod"
     secrets:

.github/workflows/fossa.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     paths-ignore:
-      - "docs/**"
+      - "site/**"
       - "examples/**"
       - "**.md"
 

.github/workflows/mend.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     paths-ignore:
-      - docs/**
+      - site/**
       - examples/**
   workflow_dispatch:
     inputs:

.gitignore

@@ -50,12 +50,9 @@ default.pem
 hack/controller-gen-*
 
 # Ignore local docs dependencies
-site/
 venv/
-docs/public
-docs/themes/f5-hugo
-.netlify/
-docs/.netlify
+site/public
+site/themes/f5-hugo
 
 # trivy container scanning cache
 .trivycache/

.markdownlint-cli2.yaml

@@ -10,7 +10,7 @@ config:
 # Define glob expressions to ignore
 ignores:
   - ".github/**"
-  - "docs/**" # Ignore docs folder for now
+  - "site/**" # Ignore docs folder for now
 
 # Fix any fixable errors
 fix: true

.pre-commit-config.yaml

@@ -1,14 +1,14 @@
 # See https://pre-commit.com for more information
 # See https://pre-commit.com/hooks.html for more hooks
-exclude: (^docs/_vendor/|.*pb2.*)
+exclude: (^site/_vendor/|.*pb2.*)
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.6.0
     hooks:
       - id: trailing-whitespace
         exclude: '(\.md|\.snap|\.avdl)$'
       - id: end-of-file-fixer
-        exclude: docs/layouts/shortcodes/nic-.*.html
+        exclude: site/layouts/shortcodes/nic-.*.html
       - id: check-yaml
         args: [--allow-multiple-documents]
         exclude: ^(charts/nginx-ingress/templates)

CODEOWNERS

@@ -1,2 +1,2 @@
 * @nginxinc/kic
-/docs/ @nginxinc/kic @nginxinc/nginx-docs
+/site/ @nginxinc/kic @nginxinc/nginx-docs

CONTRIBUTING.md

@@ -28,15 +28,15 @@ Please reserve GitHub issues for feature requests and bugs rather than general q
 
 ## Getting Started
 
-Follow our [Installation Guide](https://github.com/nginxinc/kubernetes-ingress/blob/main/docs/content/installation) to
+Follow our [Installation Guide](https://docs.nginx.com/nginx-ingress-controller/installation/) to
 get NGINX Ingress Controller up and running.
 
-Read the [documentation](https://github.com/nginxinc/kubernetes-ingress/tree/main/docs) and
+Read the [documentation](https://github.com/nginxinc/kubernetes-ingress/tree/main/site) and
 [configuration](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples) examples
 
 ### Project Structure
 
-- This Ingress Controller is written in Go and supports both the open source NGINX software and NGINX Plus.
+- NGINX Ingress Controller is written in Go and supports both the open source NGINX software and NGINX Plus.
 - The project follows a standard Go project layout
   - The main code is found at `cmd/nginx-ingress/`
   - The internal code is found at `internal/`

README.md

@@ -140,8 +140,8 @@ your links to the correct versions:
 
 | Version | Description |  Image for NGINX | Image for NGINX Plus | Installation Manifests and Helm Chart | Documentation and Examples |
 | ------- | ----------- | --------------- | -------------------- | ---------------------------------------| -------------------------- |
-| Latest stable release | For production use | Use the 3.7.0 images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-ingress-controller-image/). | Use the 3.7.0 images from the [F5 Container Registry](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image/) or the [AWS Marketplace](https://aws.amazon.com/marketplace/search/?CREATOR=741df81b-dfdc-4d36-b8da-945ea66b522c&FULFILLMENT_OPTION_TYPE=CONTAINER&filters=CREATOR%2CFULFILLMENT_OPTION_TYPE) or [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-nginx-ingress-controller/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v3.7.0/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v3.7.0/charts/nginx-ingress). | [Documentation](https://docs.nginx.com/nginx-ingress-controller/). [Examples](https://docs.nginx.com/nginx-ingress-controller/configuration/configuration-examples/). |
-| Edge/Nightly | For testing and experimenting | Use the edge or nightly images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-nginx-ingress-controller/). | [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/building-nginx-ingress-controller/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/main/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/main/charts/nginx-ingress). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/main/docs/content). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples). |
+| Latest stable release | For production use | Use the 3.7.0 images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/build-ingress-controller-image/). | Use the 3.7.0 images from the [F5 Container Registry](https://docs.nginx.com/nginx-ingress-controller/installation/pulling-ingress-controller-image/) or the [AWS Marketplace](https://aws.amazon.com/marketplace/search/?CREATOR=741df81b-dfdc-4d36-b8da-945ea66b522c&FULFILLMENT_OPTION_TYPE=CONTAINER&filters=CREATOR%2CFULFILLMENT_OPTION_TYPE) or [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/build-nginx-ingress-controller/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/v3.7.0/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/v3.7.0/charts/nginx-ingress). | [Documentation](https://docs.nginx.com/nginx-ingress-controller/). [Examples](https://docs.nginx.com/nginx-ingress-controller/configuration/configuration-examples/). |
+| Edge/Nightly | For testing and experimenting | Use the edge or nightly images from [DockerHub](https://hub.docker.com/r/nginx/nginx-ingress/), [GitHub Container](https://github.com/nginxinc/kubernetes-ingress/pkgs/container/kubernetes-ingress), [Amazon ECR Public Gallery](https://gallery.ecr.aws/nginx/nginx-ingress) or [Quay.io](https://quay.io/repository/nginx/nginx-ingress) or [build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/build-nginx-ingress-controller/). | [Build your own image](https://docs.nginx.com/nginx-ingress-controller/installation/build-nginx-ingress-controller/). | [Manifests](https://github.com/nginxinc/kubernetes-ingress/tree/main/deployments). [Helm chart](https://github.com/nginxinc/kubernetes-ingress/tree/main/charts/nginx-ingress). | [Documentation](https://github.com/nginxinc/kubernetes-ingress/tree/main/site/content). [Examples](https://github.com/nginxinc/kubernetes-ingress/tree/main/examples). |
 
 ## SBOM (Software Bill of Materials)
 

site/go.mod

@@ -0,0 +1,5 @@
+module github.com/nginxinc/kubernetes-ingress/docs
+
+go 1.23
+
+require github.com/nginxinc/nginx-hugo-theme v0.41.20 // indirect

site/go.sum

@@ -0,0 +1,2 @@
+github.com/nginxinc/nginx-hugo-theme v0.41.20 h1:6BJGRGdHW17OpkC4qbcHARo9TRrJPFrALBjFltwedf8=
+github.com/nginxinc/nginx-hugo-theme v0.41.20/go.mod h1:DPNgSS5QYxkjH/BfH4uPDiTfODqWJ50NKZdorguom8M=

site/layouts/shortcodes/nic-helm-version.html

@@ -0,0 +1 @@
+1.4.0

site/layouts/shortcodes/nic-operator-version.html

@@ -0,0 +1 @@
+2.4.0

site/layouts/shortcodes/nic-version.html

@@ -0,0 +1 @@
+3.7.0