diff --git a/.gitignore b/.gitignore index 65e8fc0..ffd2bd5 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,6 @@ dist/ .idea/ ./prm + +# Documentation site +docs/site diff --git a/README.md b/README.md index 6334387..e99df54 100644 --- a/README.md +++ b/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. diff --git a/docs.ps1 b/docs.ps1 new file mode 100644 index 0000000..e9c2982 --- /dev/null +++ b/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 +} diff --git a/docs.sh b/docs.sh new file mode 100755 index 0000000..bf34eaa --- /dev/null +++ b/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