Skip to content

Commit 6a5f485

Browse files
MariusStorhaugMariusStorhaug
committed
🩹 [Refactor]: Rename BuildDocs job to Build-Docs and streamline its steps by using a separate workflow
1 parent f6aa1f1 commit 6a5f485

File tree

3 files changed

+236
-312
lines changed

3 files changed

+236
-312
lines changed

‎.github/workflows/Build-Docs.yml

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
name: Build-Docs
2+
3+
on:
4+
workflow_call:
5+
inputs:
6+
Name:
7+
type: string
8+
description: The name of the module to process. Scripts default to the repository name if nothing is specified.
9+
required: false
10+
Path:
11+
type: string
12+
description: The path to the source code of the module.
13+
required: false
14+
default: src
15+
ModulesOutputPath:
16+
type: string
17+
description: The path to the output directory for the modules.
18+
required: false
19+
default: outputs/modules
20+
DocsOutputPath:
21+
type: string
22+
description: The path to the output directory for the documentation.
23+
required: false
24+
default: outputs/docs
25+
SiteOutputPath:
26+
type: string
27+
description: The path to the output directory for the site.
28+
required: false
29+
default: outputs/site
30+
Debug:
31+
type: boolean
32+
description: Enable debug output.
33+
required: false
34+
default: false
35+
Verbose:
36+
type: boolean
37+
description: Enable verbose output.
38+
required: false
39+
default: false
40+
Version:
41+
type: string
42+
description: Specifies the version of the GitHub module to be installed. The value must be an exact version.
43+
required: false
44+
default: ''
45+
Prerelease:
46+
type: boolean
47+
description: Whether to use a prerelease version of the 'GitHub' module.
48+
required: false
49+
default: false
50+
51+
permissions:
52+
contents: read # to checkout the repo
53+
54+
jobs:
55+
Build-Docs:
56+
name: Build-Docs
57+
runs-on: ubuntu-latest
58+
steps:
59+
- name: Checkout Code
60+
uses: actions/checkout@v4
61+
with:
62+
fetch-depth: 0
63+
64+
- name: Debug
65+
if: ${{ inputs.Debug }}
66+
uses: PSModule/Debug@v0
67+
68+
- name: Initialize environment
69+
uses: PSModule/Initialize-PSModule@v1
70+
with:
71+
Debug: ${{ inputs.Debug }}
72+
Prerelease: ${{ inputs.Prerelease }}
73+
Verbose: ${{ inputs.Verbose }}
74+
Version: ${{ inputs.Version }}
75+
76+
- name: Document module
77+
uses: PSModule/Document-PSModule@v0
78+
with:
79+
Name: ${{ inputs.Name }}
80+
Path: ${{ inputs.Path }}
81+
ModulesOutputPath: ${{ inputs.ModulesOutputPath }}
82+
DocsOutputPath: ${{ inputs.DocsOutputPath }}
83+
Debug: ${{ inputs.Debug }}
84+
Prerelease: ${{ inputs.Prerelease }}
85+
Verbose: ${{ inputs.Verbose }}
86+
Version: ${{ inputs.Version }}
87+
88+
- name: Commit all changes
89+
continue-on-error: true
90+
shell: pwsh
91+
run: |
92+
# Rename the gitignore file to .gitignore.bak
93+
Rename-Item -Path '.gitignore' -NewName '.gitignore.bak' -Force
94+
95+
try {
96+
# Add all changes to the repository
97+
git add .
98+
git commit -m 'Update documentation'
99+
} catch {
100+
Write-Host "No changes to commit"
101+
}
102+
103+
# Restore the gitignore file
104+
Rename-Item -Path '.gitignore.bak' -NewName '.gitignore' -Force
105+
106+
- name: Lint documentation
107+
uses: super-linter/super-linter/slim@latest
108+
env:
109+
FILTER_REGEX_INCLUDE: ${{ inputs.DocsOutputPath }}
110+
DEFAULT_BRANCH: main
111+
DEFAULT_WORKSPACE: ${{ github.workspace }}
112+
ENABLE_GITHUB_ACTIONS_GROUP_TITLE: true
113+
GITHUB_TOKEN: ${{ github.token }}
114+
RUN_LOCAL: true
115+
VALIDATE_ALL_CODEBASE: true
116+
VALIDATE_JSON_PRETTIER: false
117+
VALIDATE_MARKDOWN_PRETTIER: false
118+
VALIDATE_YAML_PRETTIER: false
119+
VALIDATE_GITLEAKS: false
120+
121+
- uses: actions/configure-pages@v5
122+
123+
- name: Install mkdoks-material
124+
shell: pwsh
125+
run: |
126+
pip install mkdocs-material
127+
pip install mkdocs-git-authors-plugin
128+
pip install mkdocs-git-revision-date-localized-plugin
129+
pip install mkdocs-git-committers-plugin-2
130+
131+
- name: Structure site
132+
uses: PSModule/GitHub-Script@v1
133+
with:
134+
Debug: ${{ inputs.Debug }}
135+
Prerelease: ${{ inputs.Prerelease }}
136+
Verbose: ${{ inputs.Verbose }}
137+
Version: ${{ inputs.Version }}
138+
Script: |
139+
New-Item -Path "$env:GITHUB_WORKSPACE/${{ inputs.SiteOutputPath }}/docs/Functions" -ItemType Directory -Force
140+
Copy-Item -Path "$env:GITHUB_WORKSPACE/${{ inputs.DocsOutputPath }}/*" -Destination "$env:GITHUB_WORKSPACE/${{ inputs.SiteOutputPath }}/docs/Functions" -Recurse -Force
141+
$moduleName = [string]::IsNullOrEmpty('${{ inputs.Name }}') ? $env:GITHUB_REPOSITORY_NAME : '${{ inputs.Name }}'
142+
$ModuleSourcePath = Join-Path $PWD -ChildPath '${{ inputs.Path }}'
143+
$SiteOutputPath = Join-Path $PWD -ChildPath '${{ inputs.SiteOutputPath }}'
144+
145+
LogGroup "Get folder structure" {
146+
Get-ChildItem -Recurse | Select-Object -ExpandProperty FullName | Sort-Object | Format-List
147+
}
148+
149+
$functionDocsFolder = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Functions' | Get-Item
150+
Get-ChildItem -Path $functionDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
151+
$fileName = $_.Name
152+
LogGroup " - $fileName" {
153+
Show-FileContent -Path $_
154+
}
155+
}
156+
157+
LogGroup 'Build docs - Process about topics' {
158+
$aboutDocsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/About'
159+
$aboutDocsFolder = New-Item -Path $aboutDocsFolderPath -ItemType Directory -Force
160+
$aboutSourceFolder = Get-ChildItem -Path $ModuleSourcePath -Directory | Where-Object { $_.Name -eq 'en-US' }
161+
Get-ChildItem -Path $aboutSourceFolder -Filter *.txt | Copy-Item -Destination $aboutDocsFolder -Force -Verbose -PassThru |
162+
Rename-Item -NewName { $_.Name -replace '.txt', '.md' }
163+
}
164+
165+
LogGroup 'Build docs - Copy icon to assets' {
166+
$assetsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Assets'
167+
$null = New-Item -Path $assetsFolderPath -ItemType Directory -Force
168+
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
169+
$iconPath = Join-Path -Path $rootPath -ChildPath 'icon\icon.png'
170+
Copy-Item -Path $iconPath -Destination $assetsFolderPath -Force -Verbose
171+
}
172+
173+
LogGroup 'Build docs - Copy readme.md' {
174+
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
175+
$readmePath = Join-Path -Path $rootPath -ChildPath 'README.md'
176+
$readmeTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/README.md'
177+
Copy-Item -Path $readmePath -Destination $readmeTargetPath -Force -Verbose
178+
}
179+
180+
LogGroup 'Build docs - Create mkdocs.yml' {
181+
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
182+
# This should be moved to an action so that we can use a default one, and not have to copy it from the repo.
183+
$mkdocsSourcePath = Join-Path -Path $rootPath -ChildPath 'mkdocs.yml'
184+
$mkdocsTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'mkdocs.yml'
185+
$mkdocsContent = Get-Content -Path $mkdocsSourcePath -Raw
186+
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_NAME }}-', $ModuleName)
187+
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
188+
$mkdocsContent | Set-Content -Path $mkdocsTargetPath -Force
189+
Show-FileContent -Path $mkdocsTargetPath
190+
}
191+
192+
- name: Debug File system
193+
shell: pwsh
194+
run: |
195+
Get-ChildItem -Path $env:GITHUB_WORKSPACE -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
196+
197+
- name: Build mkdocs-material project
198+
working-directory: ${{ inputs.SiteOutputPath }}
199+
shell: pwsh
200+
run: |
201+
Start-LogGroup 'Build docs - mkdocs build - content'
202+
Show-FileContent -Path mkdocs.yml
203+
Stop-LogGroup
204+
Start-LogGroup 'Build docs - mkdocs build'
205+
mkdocs build --config-file mkdocs.yml --site-dir ${{ github.workspace }}/_site
206+
Stop-LogGroup
207+
208+
- uses: actions/upload-pages-artifact@v3
209+

‎.github/workflows/CI.yml

Lines changed: 12 additions & 155 deletions
Original file line numberDiff line numberDiff line change
@@ -132,163 +132,20 @@ jobs:
132132
Verbose: ${{ inputs.Verbose }}
133133
Version: ${{ inputs.Version }}
134134

135-
BuildDocs:
136-
name: Build docs
135+
Build-Docs:
137136
needs:
138137
- Build-Module
139-
runs-on: ubuntu-latest
140-
steps:
141-
- name: Checkout Code
142-
uses: actions/checkout@v4
143-
with:
144-
fetch-depth: 0
145-
146-
- name: Debug
147-
if: ${{ inputs.Debug }}
148-
uses: PSModule/Debug@v0
149-
150-
- name: Initialize environment
151-
uses: PSModule/Initialize-PSModule@v1
152-
with:
153-
Debug: ${{ inputs.Debug }}
154-
Prerelease: ${{ inputs.Prerelease }}
155-
Verbose: ${{ inputs.Verbose }}
156-
Version: ${{ inputs.Version }}
157-
158-
- name: Document module
159-
uses: PSModule/Document-PSModule@v0
160-
with:
161-
Name: ${{ inputs.Name }}
162-
Path: ${{ inputs.Path }}
163-
ModulesOutputPath: ${{ inputs.ModulesOutputPath }}
164-
DocsOutputPath: ${{ inputs.DocsOutputPath }}
165-
Debug: ${{ inputs.Debug }}
166-
Prerelease: ${{ inputs.Prerelease }}
167-
Verbose: ${{ inputs.Verbose }}
168-
Version: ${{ inputs.Version }}
169-
170-
- name: Commit all changes
171-
continue-on-error: true
172-
shell: pwsh
173-
run: |
174-
# Rename the gitignore file to .gitignore.bak
175-
Rename-Item -Path '.gitignore' -NewName '.gitignore.bak' -Force
176-
177-
try {
178-
# Add all changes to the repository
179-
git add .
180-
git commit -m 'Update documentation'
181-
} catch {
182-
Write-Host "No changes to commit"
183-
}
184-
185-
# Restore the gitignore file
186-
Rename-Item -Path '.gitignore.bak' -NewName '.gitignore' -Force
187-
188-
- name: Lint documentation
189-
uses: super-linter/super-linter/slim@latest
190-
env:
191-
FILTER_REGEX_INCLUDE: '${{ inputs.DocsOutputPath }}/**'
192-
DEFAULT_BRANCH: main
193-
DEFAULT_WORKSPACE: ${{ github.workspace }}
194-
ENABLE_GITHUB_ACTIONS_GROUP_TITLE: true
195-
GITHUB_TOKEN: ${{ github.token }}
196-
RUN_LOCAL: true
197-
VALIDATE_ALL_CODEBASE: true
198-
VALIDATE_JSON_PRETTIER: false
199-
VALIDATE_MARKDOWN_PRETTIER: false
200-
VALIDATE_YAML_PRETTIER: false
201-
VALIDATE_GITLEAKS: false
202-
203-
- uses: actions/configure-pages@v5
204-
205-
- name: Install mkdoks-material
206-
shell: pwsh
207-
run: |
208-
pip install mkdocs-material
209-
pip install mkdocs-git-authors-plugin
210-
pip install mkdocs-git-revision-date-localized-plugin
211-
pip install mkdocs-git-committers-plugin-2
212-
213-
- name: Structure site
214-
uses: PSModule/GitHub-Script@v1
215-
with:
216-
Debug: ${{ inputs.Debug }}
217-
Prerelease: ${{ inputs.Prerelease }}
218-
Verbose: ${{ inputs.Verbose }}
219-
Version: ${{ inputs.Version }}
220-
Script: |
221-
New-Item -Path "$env:GITHUB_WORKSPACE/${{ inputs.SiteOutputPath }}/docs/Functions" -ItemType Directory -Force
222-
Copy-Item -Path "$env:GITHUB_WORKSPACE/${{ inputs.DocsOutputPath }}/*" -Destination "$env:GITHUB_WORKSPACE/${{ inputs.SiteOutputPath }}/docs/Functions" -Recurse -Force
223-
$moduleName = [string]::IsNullOrEmpty('${{ inputs.Name }}') ? $env:GITHUB_REPOSITORY_NAME : '${{ inputs.Name }}'
224-
$ModuleSourcePath = Join-Path $PWD -ChildPath '${{ inputs.Path }}'
225-
$SiteOutputPath = Join-Path $PWD -ChildPath '${{ inputs.SiteOutputPath }}'
226-
227-
LogGroup "Get folderstructure" {
228-
Get-ChildItem -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
229-
}
230-
231-
$functionDocsFolder = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Functions' | Get-Item
232-
Get-ChildItem -Path $functionDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
233-
$fileName = $_.Name
234-
$hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash
235-
LogGroup " - [$fileName] - [$hash]" {
236-
Show-FileContent -Path $_
237-
}
238-
}
239-
240-
LogGroup 'Build docs - Process about topics' {
241-
$aboutDocsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/About'
242-
$aboutDocsFolder = New-Item -Path $aboutDocsFolderPath -ItemType Directory -Force
243-
$aboutSourceFolder = Get-ChildItem -Path $ModuleSourcePath -Directory | Where-Object { $_.Name -eq 'en-US' }
244-
Get-ChildItem -Path $aboutSourceFolder -Filter *.txt | Copy-Item -Destination $aboutDocsFolder -Force -Verbose -PassThru |
245-
Rename-Item -NewName { $_.Name -replace '.txt', '.md' }
246-
}
247-
248-
LogGroup 'Build docs - Copy icon to assets' {
249-
$assetsFolderPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/Assets'
250-
$null = New-Item -Path $assetsFolderPath -ItemType Directory -Force
251-
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
252-
$iconPath = Join-Path -Path $rootPath -ChildPath 'icon\icon.png'
253-
Copy-Item -Path $iconPath -Destination $assetsFolderPath -Force -Verbose
254-
}
255-
256-
LogGroup 'Build docs - Copy readme.md' {
257-
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
258-
$readmePath = Join-Path -Path $rootPath -ChildPath 'README.md'
259-
$readmeTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'docs/README.md'
260-
Copy-Item -Path $readmePath -Destination $readmeTargetPath -Force -Verbose
261-
}
262-
263-
LogGroup 'Build docs - Create mkdocs.yml' {
264-
$rootPath = Split-Path -Path $ModuleSourcePath -Parent
265-
# This should be moved to an action so that we can use a default one, and not have to copy it from the repo.
266-
$mkdocsSourcePath = Join-Path -Path $rootPath -ChildPath 'mkdocs.yml'
267-
$mkdocsTargetPath = Join-Path -Path $SiteOutputPath -ChildPath 'mkdocs.yml'
268-
$mkdocsContent = Get-Content -Path $mkdocsSourcePath -Raw
269-
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_NAME }}-', $ModuleName)
270-
$mkdocsContent = $mkdocsContent.Replace('-{{ REPO_OWNER }}-', $env:GITHUB_REPOSITORY_OWNER)
271-
$mkdocsContent | Set-Content -Path $mkdocsTargetPath -Force
272-
Show-FileContent -Path $mkdocsTargetPath
273-
}
274-
275-
- name: Debug File system
276-
shell: pwsh
277-
run: |
278-
Get-ChildItem -Path $env:GITHUB_WORKSPACE -Recurse | Select-Object -ExpandProperty FullName | Sort-Object
279-
280-
- name: Build mkdocs-material project
281-
working-directory: ${{ inputs.SiteOutputPath }}
282-
shell: pwsh
283-
run: |
284-
Start-LogGroup 'Build docs - mkdocs build - content'
285-
Show-FileContent -Path mkdocs.yml
286-
Stop-LogGroup
287-
Start-LogGroup 'Build docs - mkdocs build'
288-
mkdocs build --config-file mkdocs.yml --site-dir ${{ github.workspace }}/_site
289-
Stop-LogGroup
290-
291-
- uses: actions/upload-pages-artifact@v3
138+
uses: ./.github/workflows/Build-Docs.yml
139+
with:
140+
Name: ${{ inputs.Name }}
141+
Path: ${{ inputs.Path }}
142+
ModulesOutputPath: ${{ inputs.ModulesOutputPath }}
143+
DocsOutputPath: ${{ inputs.DocsOutputPath }}
144+
Debug: ${{ inputs.Debug }}
145+
Prerelease: ${{ inputs.Prerelease }}
146+
Verbose: ${{ inputs.Verbose }}
147+
Version: ${{ inputs.Version }}
148+
SiteOutputPath: ${{ inputs.SiteOutputPath }}
292149

293150
# This is necessary as there is no way to get output from a matrix job
294151
TestModule-pwsh-ubuntu-latest:

0 commit comments

Comments
 (0)