Merge pull request #76 from puppetlabs/gh-75/main/docs_site_script

(GH-75) Created docs site scripts

.gitignore

@@ -21,3 +21,6 @@ dist/
 .idea/
 
 ./prm
+
+# Documentation site
+docs/site

README.md

@@ -7,6 +7,10 @@
     - [Windows Systems](#windows-systems)
   - [Requesting a feature](#requesting-a-feature)
   - [Reporting Problems](#reporting-problems)
+  - [Locally host documentation site](#locally-host-documentation-site)
+    - [Prerequisites](#prerequisites)
+    - [Install site](#install-site)
+    - [Run site](#run-site)
   - [Installing Telemetry Free Version](#installing-telemetry-free-version)
     - [Unix Systems](#unix-systems-1)
     - [Windows Systems](#windows-systems-1)
@@ -57,6 +61,47 @@ to file an issue on our GitHub repository: https://github.com/puppetlabs/prm/iss
 Make sure to fill in the information that is requested in the issue template as it
 will help us investigate the problem more quickly.
 
+
+## Locally host documentation site
+
+The DevX documentation site can be locally hosted and changes made to the markdown files inside of the `docs/md/content` directory will
+be visible on the site.
+
+### Prerequisites
+
+Essential software that will need to be installed to run the documentation site locally:
+
+- Git version control
+- Hugo extended version
+- Nodejs and NPM
+
+### Install site
+
+To install the documentation site run the following command from the root of this project:
+
+```bash
+./docs.sh
+```
+
+This will install and run the documentation site. The site can be found at `http://localhost:1313/devx`. All updates will to the
+`docs/md/content` directory will hot reload the site.
+
+To stop the running `ctrl + c` in the terminal window in which it is running.
+
+### Run site
+
+Commands to run the site locally:
+```bash
+# Run without draft pages being displayed
+./docs.sh
+```
+or
+
+```bash
+# Run with draft pages being displayed
+./docs.sh -D
+```
+
 ## Installing Telemetry Free Version
 
 We gather telemetry data to provide insights into how our products are being used.

docs.ps1

@@ -0,0 +1,61 @@
+<#
+.Description
+A script to install the DevX documentation site in the docs\site directory and run it.
+If the site is already installed, executing this script will run the site locally.
+Changes and files added to the contents of the docs\md\content directory will be displayed on this
+locally hosted site.
+#>
+
+param(
+    [Alias('D')]
+    [Switch]$BuildDrafts
+)
+
+# Check working directory is the root directory of the PRM repository
+if (!(Test-Path -Path ".\docs\md")) {
+    Throw 'Please run this script from the root directory of the PRM project.'
+}
+# Check hugo extended is installed
+if ([string]::IsNullOrEmpty((hugo version | Select-String -Pattern "extended"))) {
+    Throw 'The "extended" version of hugo was not found, please install it.'
+}
+
+# Check that git and npm are installed
+$Programs = @('git', 'npm')
+foreach ($Program in $Programs) {
+    try {
+        Get-Command -Name $Program -ErrorAction Stop
+    }
+    catch {
+        Throw "$Program was not found, please install it."
+    }
+}
+
+# Check if the docs site directory exists
+if (!(Test-Path -Path ".\docs\site")) {
+    git clone https://github.com/puppetlabs/devx.git docs\site
+    Push-Location docs\site
+    Add-Content -Path .\go.mod -value 'replace github.com/puppetlabs/prm/docs/md => ..\md'
+    npm install
+}
+else {
+    Push-Location docs\site
+    git pull
+    hugo mod clean
+}
+
+git submodule update --init --recursive --depth 50
+hugo mod get
+# Check if -D flag is set to true
+try {
+    if ($BuildDrafts) {
+        hugo server -D
+    }
+    else {
+        hugo server
+    }
+} catch {
+
+} finally {
+    Pop-Location
+}

docs.sh

@@ -0,0 +1,45 @@
+#!/bin/sh
+
+# Check working directory is the root directory of the PRM repository
+if [ ! -d "docs/md" ]; then
+    echo 'Please run this script from the root directory of the PRM project.'
+    exit 1
+fi
+# Check hugo extended is installed
+if ! hugo version | grep -q 'extended'; then
+    echo 'The "extended" version of hugo was not found, please install it.'
+    exit
+fi
+# Check git is installed
+if ! type "git" > /dev/null; then
+    echo "Git version control was not found, please install it."
+    exit
+fi
+# Check if npm is installed
+if ! type "npm" > /dev/null; then
+    echo "NPM was not found, please install it."
+    exit
+fi
+
+if [ ! -d "docs/site" ]; then
+    git clone https://github.com/puppetlabs/devx.git docs/site
+    cd docs/site
+    echo "replace github.com/puppetlabs/prm/docs/md => ../md" >> go.mod
+    npm install
+else
+    cd docs/site
+    git pull
+    hugo mod clean
+fi
+
+# Check for -D flag to see if user wants to run the site with draft pages displayed
+flag=''
+while getopts 'D' opt; do
+    case $opt in
+        D) flag='-D' ;;
+    esac
+done
+
+git submodule update --init --recursive --depth 50
+hugo mod get
+hugo server $flag