Adds support for development on windows (#501)

- Updates batch scripts from windows testing
- Updates documentation contribution info
- Fixes broken links
- Adds 3 retries to linkchecker

Signed-off-by: Sean Sundberg <[email protected]>

Author: Sean Sundberg

build.bat

@@ -0,0 +1,6 @@
+
+@echo on
+
+cspell "docs/**/*.md"
+mkdocs build
+linkchecker -f linkcheckerrc public

build.sh

@@ -4,4 +4,4 @@ set -e
 
 cspell "docs/**/*.md"
 mkdocs build
-linkchecker -f linkcheckerrc public
+linkchecker -r 3 -f linkcheckerrc public

dev/Dockerfile

@@ -1,6 +1,6 @@
 FROM squidfunk/mkdocs-material:7.1.8
 
-RUN apk add --no-cache --update nodejs npm
+RUN apk add --no-cache --update nodejs npm dos2unix
 
 WORKDIR /site
 COPY ./package*.json /site/
@@ -10,6 +10,6 @@ RUN pip --no-cache-dir install git+https://github.com/linkchecker/linkchecker@v1
 # NodeJS Dependencies
 RUN npm ci
 COPY dev/entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh
+RUN dos2unix /entrypoint.sh && chmod +x /entrypoint.sh
 
 ENTRYPOINT ["/entrypoint.sh"]

dev/build.bat

@@ -0,0 +1,8 @@
+
+set IMAGE=%1
+if "%IMAGE%"=="" (set IMAGE=devguide-dev)
+
+set SCRIPT_DIR=%~dp0
+set ROOT_DIR="%SCRIPT_DIR%.."
+
+docker build -t %IMAGE% -f %SCRIPT_DIR%Dockerfile %ROOT_DIR%

dev/clean.bat

@@ -0,0 +1,8 @@
+
+set NAME=%1
+if "%NAME%"=="" (set NAME=devguide-dev)
+
+ECHO "Cleaning up old container '%NAME%'..."
+docker rm "%NAME%" --force 1>NUL 2>NUL
+
+echo "Finished clean up"

dev/logs.bat

@@ -0,0 +1,5 @@
+
+set NAME=%1
+if "%NAME%"=="" (set NAME=devguide-dev)
+
+docker logs -f %NAME%

dev/run.bat

@@ -0,0 +1,14 @@
+
+set NAME=%1
+if "%NAME%"=="" (set NAME=devguide-dev)
+
+set PORT=%2
+if "%PORT%"=="" (set PORT=8000)
+
+set IMAGE=%3
+if "%IMAGE%"=="" (set IMAGE=devguide-dev)
+
+docker run --name %NAME% -d -p %PORT%:%PORT% -v "%cd%:/site" %IMAGE%
+echo "Dev environment running with live reloading enabled. Open http://localhost:%PORT% to see the site"
+echo "For live logs run:"
+echo "docker logs -f %NAME%"

docs/contribute/documentation.md

@@ -8,19 +8,42 @@ To work on documentation and be able to view the rendered web site you need to c
 
 === "Tooling within a Docker container"
 
-    You can use a Docker container and run MkDocs from the container, so no local installation is required:
+    You can use a Docker container and run MkDocs from the container, so no local installation is required.
+
+    **Prerequisites**
 
     - You need to have [Docker](https://www.docker.com) installed and running on your system
     - There are helper configurations installed if you have npm from [Node.JS](https://nodejs.org) installed.
-    - Build the development docker container image, this is only need it once if the dependencies have not changed. Run `npm run dev:build`
+
+    **Setup**
+
+    Build the development docker container image, this is only need it once if the dependencies have not changed.
+
+    - Run `npm run dev:build`
+
+    **Work with the development environment**
+
+    _Start_
+
     - To start developing run command `npm run dev` in the root directory of the git repo (where **package.json** and **mkdocs.yaml** are located)
     - Open a browser to `http://localhost:8000`, where you will see the documentation site.  This will live update as you save changes to the Markdown files in the docs folder
-    - To stop developing run command `npm dev:stop` in another terminal window, which will terminate the docker container
-    - View the scripts section of **package.json** in the root folder of the git repo for additional options available
-    - To build the static HTML file and check all links and spelling run command `npm run build`
+
+    _Stop_
+
+    - Run `npm dev:stop` in another terminal window, which will terminate the docker container
+
+    _Link checker_
+
     - To check links in the built site (`npm run build` must be run first), use the linkchecker, with command `npm run dev:links`.  This command should be run in the root folder of the project, containing the **linkcheckerrc** file.
+
+    _Spell checker_
+
     - To check spelling `npm run dev:spell` should be run in the root folder of the project, containing the **cspell.json** file.
 
+    _Build static site_
+
+    - To build the static HTML file and check all links and spelling run command `npm run build`
+
 === "Local mkdocs and python tooling installation"
 
     You can install MkDocs and associated plugins on your development system and run the tools locally:

docs/learning/dev-setup.md

@@ -40,7 +40,7 @@ To install the IBM Cloud CLI follow the instructions in the [IBM Cloud documenta
 
 The oc command is available from all installations of RedHat OpenShift or CodeReady Containers.  Navigate and log into the web console for the cluster, then in the dropdown accessed by clicking the help icon (a question mark next to you username at the top of the web console) you will find a link to the install images for various operating systems.
 
-The install images are also available to download from [RedHat](https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/){: target=_blank}.  Be sure to get the latest version of the oc command.
+The install images are also available to download from [RedHat](https://mirror.openshift.com/pub/openshift-v4/x86_64/clients/ocp/stable/){: target=_blank}.  Be sure to get the latest version of the oc command.
 
 ## User accounts
 

docs/reference/tools/sonar-qube.md

@@ -10,7 +10,7 @@ SonarQube performs static code analysis to evaluate code quality, using analysis
 - **Application Security**: Detect vulnerabilities and hot spots that can be exploited to compromise the program
 - **Technical Debt**: Keep you codebase maintainable to increase developer velocity
 
-SonarQube [plugs into the application lifecycle management (ALM)](https://docs.sonarqube.org/latest/architecture/architecture-integration/#header-2) process to make continuous inspection part of continuous integration. Adding code analysis to ALM provides regular, timely feedback on the quality of the code being produced. The goal is to detect problems as soon as possible so that they can be resolved before they can impact production end users.
+SonarQube [plugs into the application lifecycle management (ALM)](https://docs.sonarqube.org/latest/#header-1) process to make continuous inspection part of continuous integration. Adding code analysis to ALM provides regular, timely feedback on the quality of the code being produced. The goal is to detect problems as soon as possible so that they can be resolved before they can impact production end users.
 
 The continuous integration (CI) server integrates SonarQube into the ALM.The SonarQube solution consists of several components: The central component is the SonarQube Server, which runs the SonarScanner, processes the resulting analysis reports, stores the reports in SonarQube Database, and displays the reports in the SonarQube UI. A CI server uses a stage/goal/task in its build automation to trigger the language-specific SonarScanner to scan the code being built. Developers can view the resulting analysis report in the SonarQube UI.