MakeDocs!
Creating docs for software projects is not glamorous. MakeDocs will help you get started with some simple docs quickly and easily. It is just some tooling, scripts really, to ask you a couple of questions combined with some cursory inspection of your repo to get you started with a static site generator under some build infrastructure.
This will install a copy of the toolchain needed to create docs. Afterwards you can adjust anything required to make it work better in your project.
Let's Go!
Linux/WSL/etc
bash <(curl -sL makedocs.io)
Windows
irm makedocs.io | iex
How Does It Work?
You execute the installation script for MakeDocs from one of the above commands. It will prompt you to choose a generator, check your repository for existing GitHub Actions or Gitlab Pipelines or ask to install new CICD templates.
Afterwards we grab a package related to your selections and install the generator with optional automation files.
Flows
Project layout
Using all the defaults for the installation this is what the new additions to your source tree will look like!
├─ Makefile # Appended include statement for the sub-Makefile
└─ docs # Configurable documentation system directory
├─ Dockerfile # Dockerfile used to build/serve your site
├─ Makefile # Sub-Makefile to provide automation
├─ docs|content # Documentation site content directory
│ └─ index.md # The documentation homepage with sample content
└─ mkdocs.yml|config.toml # Static site's configuration file
The Scripts
You can either download the scripts below or just run them from our url at http://makedocs.io/. Thanks Content Negotiation!
via Bash
bash <(curl -sL makedocs.io)
#!/usr/bin/env bash
SOURCE_URL=https://makedocs.io
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
VERSION=0.6.0
PATH_SEPERATOR='\'
CWD=${PWD##*/}
DOCS_DIR_DEFAULT=docs
echo
echo "**********************************************************************************"
echo "* *"
echo "* Welcome to makedocs.io - Follow the prompts & let's create your project docs *"
echo "* *"
echo "**********************************************************************************"
echo "* version: $VERSION commit: $COMMIT_HASH *"
echo "**********************************************************************************"
echo
echo "Would you like to install Mkdocs or Hugo?"
select yn in "Mkdocs" "Hugo" "None"; do
case $yn in
Mkdocs ) GENERATOR=mkdocs; break;;
Hugo ) GENERATOR=hugo; break;;
None ) echo "Thanks for visiting makedocs.io!" ;exit; break;;
esac
done
[[ -f ".gitlab-ci.yml" ]] && GITLAB_EXISTS=true || GITLAB_EXISTS=false
[[ -d ".github" ]] && GITHUB_EXISTS=true || GITHUB_EXISTS=false
if [[ "$GITLAB_EXISTS" == "false" && "$GITHUB_EXISTS" == "false" ]]; then
echo "There is no GitHub or Gitlab CI found. Would you like to start one?"
select yn in "GitHub" "Gitlab" "None"; do
case $yn in
GitHub ) SKIP_CI=false; ADD_GITHUB_PIPELINE=true; break;;
Gitlab ) SKIP_CI=false; ADD_GITLAB_PIPELINE=true; break;;
None ) SKIP_CI=true; break;;
esac
done
fi
if [[ "$SKIP_CI"="false" && "$GITLAB_EXISTS" == "false" && "$GITHUB_EXISTS" == "true" ]]; then
echo "Would you like to add to existing GitHub Actions?"
select yn in "Yes" "No"; do
case $yn in
Yes ) ADD_GITHUB_PIPELINE=true; break;;
No ) ADD_GITHUB_PIPELINE=false; break;;
esac
done
fi
if [[ "$SKIP_CI"="false" && "$GITLAB_EXISTS" == "true" && "$GITHUB_EXISTS" == "false" ]]; then
echo "Would you like to add to existing Gitlab CI stages?"
select yn in "Yes" "No"; do
case $yn in
Yes ) ADD_GITLAB_PIPELINE=true; break;;
No ) ADD_GITLAB_PIPELINE=false; break;;
esac
done
fi
echo "Downloading installation script for $GENERATOR"
bash <(curl -sL http://makedocs.io/${COMMIT_HASH}-${GENERATOR}-docs.sh#${COMMIT_HASH})
if [[ "$SKIP_CI"="false" ]]; then
SUBMAKEFILE="docs/Makefile"
if [[ "$ADD_GITHUB_PIPELINE" == "true" ]]; then
echo "Adding GitHub Actions to project"
mkdir -p .github
mkdir -p .github/workflows
cat $DOCS_DIR_DEFAULT/ci/.github/workflows/makedocs-generation.yml >> .github/workflows/makedocs-generation.yml
# GitHub Pages are published into a site directory
sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=site/g" $SUBMAKEFILE
fi
if [[ "$ADD_GITLAB_PIPELINE" == "true" ]]; then
echo "Adding Gitlab Pipelines to project"
cat $DOCS_DIR_DEFAULT/ci/.gitlab-ci.yml >> .gitlab-ci.yml
# Gitlab Pages are published into a public directory
sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=public/g" $SUBMAKEFILE
fi
fi
echo "Adding Makefile include to $GENERATOR sub Makefile"
echo "include $DOCS_DIR_DEFAULT/Makefile" >> Makefile
echo "Cleaning up"
rm -rf $DOCS_DIR_DEFAULT/ci
GENERATOR=mkdocs
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
ARCHIVE="${COMMIT_HASH}-${GENERATOR}-docs.tar.gz"
ARCHIVEURL="https://makedocs.io/$ARCHIVE"
CHECKSUMURL="https://makedocs.io/checksum.txt"
SCRIPT_ROOT=$(pwd)
echo "Downloading"
echo " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
curl -sL $CHECKSUMURL | grep -i $ARCHIVE > "$SCRIPT_ROOT/checksum.txt"
echo " - archive $ARCHIVEURL to $SCRIPT_ROOT"
curl -sL $ARCHIVEURL --output "$SCRIPT_ROOT/$ARCHIVE"
echo -n "Validating checksum of "
sha256sum --check "checksum.txt"
echo "Extracting"
echo " - archive $SCRIPT_ROOT/$ARCHIVE"
tar --extract --file "$SCRIPT_ROOT/$ARCHIVE" -C "$SCRIPT_ROOT/"
echo "Cleaning up"
rm -rf "$SCRIPT_ROOT/$ARCHIVE"
rm -rf "$SCRIPT_ROOT/checksum.txt"
GENERATOR=hugo
COMMIT_HASH=9b76e69919e33d005eb2e555596f10ddf2e75069
ARCHIVE="${COMMIT_HASH}-${GENERATOR}-docs.tar.gz"
ARCHIVEURL="https://makedocs.io/$ARCHIVE"
CHECKSUMURL="https://makedocs.io/checksum.txt"
SCRIPT_ROOT=$(pwd)
echo "Downloading"
echo " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
curl -sL $CHECKSUMURL | grep -i $ARCHIVE > "$SCRIPT_ROOT/checksum.txt"
echo " - archive $ARCHIVEURL to $SCRIPT_ROOT"
curl -sL $ARCHIVEURL --output "$SCRIPT_ROOT/$ARCHIVE"
echo -n "Validating checksum of "
sha256sum --check "checksum.txt"
echo "Extracting"
echo " - archive $SCRIPT_ROOT/$ARCHIVE"
tar --extract --file "$SCRIPT_ROOT/$ARCHIVE" -C "$SCRIPT_ROOT/"
echo "Cleaning up"
rm -rf "$SCRIPT_ROOT/$ARCHIVE"
rm -rf "$SCRIPT_ROOT/checksum.txt"
via PowerShell
irm makedocs.io | iex
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
$SOURCE_URL = "https://makedocs.io"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$VERSION="0.6.0"
$PATH_SEPERATOR = [IO.Path]::DirectorySeparatorChar
$CWD = Get-Item -Path .\ | Select-Object -ExpandProperty Name
$DOCS_DIR_DEFAULT = "docs"
Write-Host
Write-Host "**********************************************************************************"
Write-Host "* *"
Write-Host "* Welcome to makedocs.io - Follow the prompts & let's create your project docs *"
Write-Host "* *"
Write-Host "**********************************************************************************"
Write-Host "* version: $VERSION commit: $COMMIT_HASH *"
Write-Host "**********************************************************************************"
Write-Host
$SKIP_CI = $true
$ADD_GITHUB_PIPELINE = $false
$ADD_GITLAB_PIPELINE = $false
function Get-ChoiceValue {
[CmdletBinding()]
param(
[string]$Title,
[string]$Message,
[array]$Options
)
$optionArray = [System.Management.Automation.Host.ChoiceDescription[]] @()
$Options | ForEach-Object {
if (($($_) -like "*&*")) {
$optionArray += New-Object System.Management.Automation.Host.ChoiceDescription $_, (($_) -replace "&", "")
}
else {
$optionArray += "&$($_)"
}
}
$result = $host.ui.PromptForChoice($Title, $Message, $optionArray, 0)
return ($Options[$result]) -replace "&", ""
}
function Get-BooleanValue {
[CmdletBinding()]
param(
[string]$Title,
[string]$Message,
[boolean]$Default
)
$index = if ($Default) { 0 } else { 1 }
$enabled = New-Object System.Management.Automation.Host.ChoiceDescription "&Yes", "Enable $Title"
$disabled = New-Object System.Management.Automation.Host.ChoiceDescription "&No", "Disable $Title"
$options = [System.Management.Automation.Host.ChoiceDescription[]]($enabled, $disabled)
$result = $Host.UI.PromptForChoice($Title, $Message, $options, $index)
$flag = if ($result) { $false } else { $true }
return $flag
}
$GENERATOR = Get-ChoiceValue -Message "Would you like to install Mkdocs or Hugo?" -Options @( "&mkdocs", "&hugo" )
if (Test-Path -Path ".github") { $GITHUB_EXISTS = $true } else { $GITHUB_EXISTS = $false }
if (Test-Path -Path ".gitlab-ci.yml") { $GITLAB_EXISTS = $true } else { $GITLAB_EXISTS = $false }
if ($GITLAB_EXISTS -eq $false -and $GITHUB_EXISTS -eq $false) {
$RESULT = Get-ChoiceValue `
-Message "There is no CI pipeline found. Would you like to start one?" `
-Options @( "&none", "git&hub", "git&lab" )
switch ($RESULT) {
"github" { $SKIP_CI = $false; $ADD_GITHUB_PIPELINE = $true }
"gitlab" { $SKIP_CI = $false; $ADD_GITLAB_PIPELINE = $true }
"&none" { $SKIP_CI = $true; $ADD_GITLAB_PIPELINE = $false; $ADD_GITHUB_PIPELINE = $false }
Default { $SKIP_CI = $true; }
}
}
elseif ($GITHUB_EXISTS -eq $true) {
$ADD_GITHUB_PIPELINE = Get-BooleanValue -Message "Would you like to add to existing GitHub Actions?" -Default $false
}
elseif ($GITLAB_EXISTS -eq $true) {
$ADD_GITLAB_PIPELINE = Get-BooleanValue -Message "Would you like to add to existing Gitlab pipeline?" -Default $false
}
Write-Host "Downloading installation script for $GENERATOR"
Invoke-RestMethod "http://makedocs.io/$COMMIT_HASH-$GENERATOR-docs.ps1#$COMMIT_HASH" | Invoke-Expression
if ($SKIP_CI -eq $false) {
$subMakeFile = "$DOCS_DIR_DEFAULT/Makefile"
if ($ADD_GITHUB_PIPELINE -eq $true) {
Write-Host "Adding GitHub Actions to project"
New-Item -Force -ItemType Directory -Path ".github" | Out-Null
New-Item -Force -ItemType Directory -Path ".github/workflows" | Out-Null
Get-Content $DOCS_DIR_DEFAULT/ci/.github/workflows/makedocs-generation.yml >> .github/workflows/makedocs-generation.yml
# GitHub Pages are published into a site directory
sed -i -E "s/export PUBLISH_DIR:=.*/export PUBLISH_DIR:=site/g" $subMakeFile
(Get-Content $subMakeFile) -replace 'export PUBLISH_DIR:=.*', 'export PUBLISH_DIR:=site' | Out-File $subMakeFile
}
if ( $ADD_GITLAB_PIPELINE -eq $true) {
Write-Host "Adding Gitlab Pipelines to project"
Add-Content -Path ".gitlab-ci.yml" -Value (Get-Content "$DOCS_DIR_DEFAULT/ci/.gitlab-ci.yml")
# Gitlab Pages are published into a public directory
(Get-Content $subMakeFile) -replace 'export PUBLISH_DIR:=.*', 'export PUBLISH_DIR:=public' | Out-File $subMakeFile
}
}
Write-Host "Adding Makefile include to $GENERATOR sub Makefile"
Add-Content -Value "include $DOCS_DIR_DEFAULT/Makefile" -Path "Makefile"
Write-Host "Cleaning up"
Remove-Item -Recurse -Force (Join-Path -Path $DOCS_DIR_DEFAULT -ChildPath "ci")
$GENERATOR = "mkdocs"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$ARCHIVE = "$COMMIT_HASH-$GENERATOR-docs.zip"
$ARCHIVEURL = "https://makedocs.io/$ARCHIVE"
$CHECKSUMURL = "https://makedocs.io/checksum.txt"
$SCRIPT_ROOT = if ([string]::IsNullOrWhiteSpace($PSScriptRoot)) { Get-Location } else { $PSScriptRoot }
Write-Host "Downloading"
Write-Host " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
(Invoke-RestMethod -Uri $CHECKSUMURL) -split "`n" | Select-String -Raw -Pattern $ARCHIVE | Out-File -FilePath $SCRIPT_ROOT\checksum.txt
Write-Host " - archive $ARCHIVEURL to $SCRIPT_ROOT"
Invoke-RestMethod -Uri $ARCHIVEURL -OutFile "$SCRIPT_ROOT\$ARCHIVE"
Write-Host -NoNewline "Validating checksum of $SCRIPT_ROOT\$ARCHIVE"
$HASH = (Get-FileHash -Path "$SCRIPT_ROOT\$ARCHIVE" -Algorithm SHA256).Hash
if (!(Select-String -Raw -Path "$SCRIPT_ROOT\checksum.txt" -Pattern $HASH -SimpleMatch)) {
Write-Error 'Download failed hash check!'
exit
}
Write-Host -ForegroundColor Green " Passed"
Write-Host "Checking for existing docs directory"
if (Test-Path "$SCRIPT_ROOT\docs") {
Write-Host -ForegroundColor Yellow "$SCRIPT_ROOT\docs already exists"
Write-Host -ForegroundColor Yellow "Please manually expand $SCRIPT_ROOT\$ARCHIVE and configure the following directory tree structure"
Write-Host -ForegroundColor Yellow "Repository Root"
Write-Host -ForegroundColor Yellow "└── docs # Configurable documentation system directory"
Write-Host -ForegroundColor Yellow " ├── Dockerfile # Dockerfile used to build/serve your site"
Write-Host -ForegroundColor Yellow " ├── Makefile # Sub-Makefile to provide automation"
Write-Host -ForegroundColor Yellow " ├── content # Configurable documentation content directory"
Write-Host -ForegroundColor Yellow " │ └── index.md # The documentation homepage with sample content"
Write-Host -ForegroundColor Yellow " └── mkdocs.yml # Mkdocs configuration file"
return
}
Write-Host "Extracting"
Write-Host " - archive $ARCHIVE"
Expand-Archive -Path "$SCRIPT_ROOT\$ARCHIVE" -DestinationPath "$SCRIPT_ROOT"
Write-Host "Cleaning up"
Remove-Item -Force -Recurse "$ARCHIVE"
Remove-Item -Force -Recurse "$SCRIPT_ROOT/checksum.txt"
$GENERATOR = "hugo"
$COMMIT_HASH="9b76e69919e33d005eb2e555596f10ddf2e75069"
$ARCHIVE = "$COMMIT_HASH-$GENERATOR-docs.zip"
$ARCHIVEURL = "https://makedocs.io/$ARCHIVE"
$CHECKSUMURL = "https://makedocs.io/checksum.txt"
$SCRIPT_ROOT = if ([string]::IsNullOrWhiteSpace($PSScriptRoot)) { Get-Location } else { $PSScriptRoot }
Write-Host "Downloading"
Write-Host " - archive $CHECKSUMURL sha file to $SCRIPT_ROOT"
(Invoke-RestMethod -Uri $CHECKSUMURL) -split "`n" | Select-String -Raw -Pattern $ARCHIVE | Out-File -FilePath $SCRIPT_ROOT\checksum.txt
Write-Host " - archive $ARCHIVEURL to $SCRIPT_ROOT"
Invoke-RestMethod -Uri $ARCHIVEURL -OutFile "$SCRIPT_ROOT\$ARCHIVE"
Write-Host -NoNewline "Validating checksum of $SCRIPT_ROOT\$ARCHIVE"
$HASH = (Get-FileHash -Path "$SCRIPT_ROOT\$ARCHIVE" -Algorithm SHA256).Hash
if (!(Select-String -Raw -Path "$SCRIPT_ROOT\checksum.txt" -Pattern $HASH -SimpleMatch)) {
Write-Error 'Download failed hash check!'
exit
}
Write-Host -ForegroundColor Green " Passed"
Write-Host "Checking for existing docs directory"
if (Test-Path "$SCRIPT_ROOT\docs") {
Write-Host -ForegroundColor Yellow "$SCRIPT_ROOT\docs already exists"
Write-Host -ForegroundColor Yellow "Please manually expand $SCRIPT_ROOT\$ARCHIVE and configure the following directory tree structure"
Write-Host -ForegroundColor Yellow "Repository Root"
Write-Host -ForegroundColor Yellow "└── docs # Configurable documentation system directory"
Write-Host -ForegroundColor Yellow " ├── Dockerfile # Dockerfile used to build/serve your site"
Write-Host -ForegroundColor Yellow " ├── Makefile # Sub-Makefile to provide automation"
Write-Host -ForegroundColor Yellow " ├── content # Configurable documentation content directory"
Write-Host -ForegroundColor Yellow " │ └── index.md # The documentation homepage with sample content"
Write-Host -ForegroundColor Yellow " └── mkdocs.yml # Mkdocs configuration file"
return
}
Write-Host "Extracting"
Write-Host " - archive $ARCHIVE"
Expand-Archive -Path "$SCRIPT_ROOT\$ARCHIVE" -DestinationPath "$SCRIPT_ROOT"
Write-Host "Cleaning up"
Remove-Item -Force -Recurse "$ARCHIVE"
Remove-Item -Force -Recurse "$SCRIPT_ROOT/checksum.txt"
Dockerfile
The docker image is used for local development as well as in CICD for deploying your documentation along with your project.
make docs_docker_build
FROM alpine:latest
ENV PYTHONUNBUFFERED=1
ENV TZ=US/Mountain
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
RUN apk update && \
apk add --update \
bash \
ca-certificates \
curl \
docker-cli \
dos2unix \
git \
gnupg \
make \
py3-pip \
python3 \
tar \
zip
# https://www.mkdocs.org/ https://mkdocs-macros-plugin.readthedocs.io/ https://squidfunk.github.io/mkdocs-material/
RUN pip3 install --no-cache --upgrade pip setuptools
RUN pip3 install mkdocs mkdocs-macros-plugin mkdocs-material
FROM alpine:latest
ENV TZ=US/Mountain
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone
RUN apk update && \
apk add --update \
bash \
ca-certificates \
curl \
docker-cli \
dos2unix \
git \
libc6-compat \
libstdc++ \
make \
tar \
unzip \
zip
# Hugo install
ENV HUGO_VERSION="0.88.1"
RUN curl -sL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz --output /tmp/hugo.tar.gz && \
tar -xf /tmp/hugo.tar.gz -C /usr/local/bin && \
rm -rf /tmp/*
Build it with Make
Part of the installation is the addition of a sub-make file. This wraps all the tasks needed to build, serve and publish your docs. We will add a small include in your root Makefile if we detect one.
Make Command | Description |
---|---|
docs_build | Builds the content to the 'site' directory |
docs_clean | Removes the content artifacts directories and archive |
docs_debug | Runs the docker image interactively for debugging purposes |
docs_docker_build | Build the docker image used for these make targets not within DIND |
docs_package | Builds the content to a compressed archive |
docs_publish | Builds the content to the 'PUBLISH_DIR' directory |
docs_serve | Runs the static site generation server |
.DEFAULT_GOAL := help
help:
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sed -E "s/(.*)?Makefile\://g" | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'
export DOCS_DIR_NAME ?= content
export DOCS_SRC ?= docs
export PUBLISH_DIR ?= public
export REPO_URL ?= https://example.com/repo
export SITE_DIR ?= site
export SITE_NAME ?= Sample-Site
export PROTOCOL ?= http
export DOMAIN_NAME ?= 127.0.0.1:8000
export SITE_URL ?= $(PROTOCOL)://$(DOMAIN_NAME)/
export LOCAL_PORT ?= 8000
ifeq ($(OS),Windows_NT)
SHELL := '/usr/bin/sh.exe'
PWD := $(shell sh.exe -c pwd)
else
SHELL := /bin/bash
endif
export BASH_CMD := $(SHELL) -c
export COMMIT_HASH ?= $(shell [[ -d ".git" ]] && git rev-parse HEAD)
export SHORT_COMMIT_HASH ?= $(shell [[ -d ".git" ]] && git rev-parse --short HEAD)
export REPO_ROOT := $(shell [[ -n "${CI}" ]] && echo $(PWD) || echo '/app' )
export VERSION ?= $(shell [[ -d ".git" ]] && git tag --sort=v:refname | grep -E '[0-9]' | tail -1 || echo 0.0.0)
export IMAGE_NAME ?= makedocsio
export IMAGE_VERSION ?= latest
export IMAGE_TAG = $(IMAGE_NAME):$(IMAGE_VERSION)
export ADDITIONAL_BUILD_ARGS ?=
export DOCS_SRC_PATH=$(REPO_ROOT)/$(DOCS_SRC)
export PUBLISH_PATH := $(REPO_ROOT)/$(PUBLISH_DIR)
export CONTENT_SITE_PATH=$(DOCS_SRC_PATH)/$(DOCS_DIR_NAME)
export DOCS_SITE_PATH=$(DOCS_SRC_PATH)/$(SITE_DIR)
ifdef CI
export IMAGE_TAG=
export DOCKER_COMMAND :=
else
export DOCKER_COMMAND := docker run -it \
-v $(PWD):$(REPO_ROOT) \
--env CI=TRUE \
--env COMMIT_HASH=$(COMMIT_HASH) \
--env COMMIT_HASH_LENGTH=$(COMMIT_HASH_LENGTH) \
--env CONTENT_SITE_PATH=$(CONTENT_SITE_PATH) \
--env DOCS_DIR=$(DOCS_DIR_NAME) \
--env DOCS_SITE_PATH=$(DOCS_SITE_PATH) \
--env DOCS_SRC_PATH=$(DOCS_SRC_PATH) \
--env LOCAL_PORT=$(LOCAL_PORT) \
--env PUBLISH_PATH=$(PUBLISH_PATH) \
--env REPO_ROOT=$(REPO_ROOT) \
--env REPO_URL=$(REPO_URL) \
--env SITE_DIR=$(SITE_DIR) \
--env SITE_NAME="$(SITE_NAME)" \
--env SITE_URL=$(SITE_URL) \
--name $(IMAGE_NAME) \
--rm
endif
bump_patch:
$(eval CMD := semver bump patch $(VERSION) )
@BUMP=$(shell $(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)') && \
echo "Bumping version from $(VERSION) to $$BUMP" && \
git tag -a -m "$$BUMP" $$BUMP
docker_build:
docker build --pull $(ADDITIONAL_BUILD_ARGS) -t $(IMAGE_TAG) . -f Dockerfile
debug: ## Runs the docker image interactively for debugging purposes
@$(DOCKER_COMMAND) $(ADDITIONAL_BUILD_ARGS) $(IMAGE_TAG) $(CMD)
clean_makedocsio:
$(eval CMD := \
mkdir -p $(REPO_ROOT)/public && rm -rf $(REPO_ROOT)/public/* && \
rm -rf $(REPO_ROOT)/hugo/*-hugo-docs.tar.gz && rm -rf $(REPO_ROOT)/hugo/*-hugo-docs.zip && \
rm -rf $(REPO_ROOT)/mkdocs/*-mkdocs-docs.tar.gz && rm -rf $(REPO_ROOT)/mkdocs/*-mkdocs-docs.zip && \
rm -rf $(DOCS_SITE_PATH) \
)
@echo "Cleaning $(SITE_DIR).zip & $(SITE_DIR) in $(SITE_DIR)"
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
build_makedocsio:
$(eval CMD := echo "Starting build" && \
build && \
cp /theme.list $(DOCS_SITE_PATH)/ && \
echo "Post build processing complete" \
)
@echo "Building"
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
publish_pre_process:
$(eval CMD := echo "Pre-processing" && \
sed -i -E "s/\$?SOURCE_URL\s?\=\s?.*/SOURCE_URL\=$(PROTOCOL)\:\/\/$(DOMAIN_NAME)/g" $(CONTENT_SITE_PATH)/*.sh && \
sed -i -E "s/\$?SOURCE_URL\s?\=\s?.*/\$`SOURCE_URL\ = \"$(PROTOCOL)\:\/\/$(DOMAIN_NAME)\"/g" $(CONTENT_SITE_PATH)/*.ps1 && \
sed -i -E "s/\$?VERSION\s?\=\s?.*/VERSION\=$(VERSION)/g" $(CONTENT_SITE_PATH)/*.sh && \
sed -i -E "s/\$?VERSION\s?\=\s?.*/\$`VERSION\=\"$(VERSION)\"/g" $(CONTENT_SITE_PATH)/*.ps1 && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(CONTENT_SITE_PATH)/*.sh && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(CONTENT_SITE_PATH)/*.ps1 && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(REPO_ROOT)/hugo/*.sh && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(REPO_ROOT)/hugo/*.ps1 && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/COMMIT_HASH\=$(COMMIT_HASH)/g" $(REPO_ROOT)/mkdocs/*.sh && \
sed -i -E "s/\$?COMMIT_HASH\s?\=\s?.*/\$`COMMIT_HASH\=\"$(COMMIT_HASH)\"/g" $(REPO_ROOT)/mkdocs/*.ps1 \
)
@echo "Pre-processing"
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
publish_all: publish_pre_process publish_mkdocs publish_hugo publish_makedocsio
$(eval CMD := cd $(REPO_ROOT)/public && sha256sum *-docs.* > checksum.txt)
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
publish_makedocsio: build_makedocsio
$(eval CMD := \
mkdir -p $(PUBLISH_PATH) && \
cp -R $(DOCS_SITE_PATH)/* $(PUBLISH_PATH)/ && \
echo "Publishing" \
)
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
publish_mkdocs:
$(eval CMD := \
cd $(REPO_ROOT)/mkdocs && \
new-mkdocs-site $(COMMIT_HASH) && \
mkdir -p $(REPO_ROOT)/public && \
cp -f $(REPO_ROOT)/mkdocs/*mkdocs-docs.* $(REPO_ROOT)/public/ && \
mv $(REPO_ROOT)/public/mkdocs-docs.ps1 $(REPO_ROOT)/public/$(COMMIT_HASH)-mkdocs-docs.ps1 && \
mv $(REPO_ROOT)/public/mkdocs-docs.sh $(REPO_ROOT)/public/$(COMMIT_HASH)-mkdocs-docs.sh \
)
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
publish_hugo:
$(eval CMD := \
cd $(REPO_ROOT)/hugo && \
new-hugo-site $(COMMIT_HASH) && \
mkdir -p $(REPO_ROOT)/public && \
cp -f $(REPO_ROOT)/hugo/*hugo-docs.* $(REPO_ROOT)/public/ && \
mv $(REPO_ROOT)/public/hugo-docs.ps1 $(REPO_ROOT)/public/$(COMMIT_HASH)-hugo-docs.ps1 && \
mv $(REPO_ROOT)/public/hugo-docs.sh $(REPO_ROOT)/public/$(COMMIT_HASH)-hugo-docs.sh \
)
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
package_makedocs:
$(eval CMD := cd $(DOCS_SRC_PATH) && zip -r ../$(SITE_DIR).zip ./)
@echo "Packaging"
$(DOCKER_COMMAND) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
serve_makedocsio:
$(eval CMD := serve)
$(DOCKER_COMMAND) -p $(LOCAL_PORT):$(LOCAL_PORT) --expose $(LOCAL_PORT) $(IMAGE_TAG) $(BASH_CMD) '$(CMD)'
create_changelog:
echo "No change log entries to show at this time" > CHANGELOG && \
docker run --rm --env _GIT_LIMIT=366 --env _GIT_LOG_OPTIONS="--ignore-all-space --ignore-blank-lines" -v $(PWD):/git arzzen/git-quick-stats /bin/bash -c "git-quick-stats -c | tail -n +4 | uniq | tee CHANGELOG"
print-%: ; @echo $*=$($*)
printenv:
printenv | sort