Skip to content

Commit 10fc17b

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
authored
⚙️ [Maintenance]: Authored Functions landing pages stay published (#409)
Modules can carry an authored `src/functions/public/index.md` that becomes the top-level Functions landing page in the generated documentation, giving readers a stable introduction before they drill into grouped commands. ## Changed: Authored Functions landing pages stay published An authored root Functions page is preserved in the generated documentation artifact as `outputs/docs/index.md`, so it is published as `Functions/index.md` without requiring module authors to change their existing documentation workflow. --- <details> <summary>Technical details</summary> - Added authored root index fixtures to `tests/srcTestRepo` and `tests/srcWithManifestTestRepo`. - Extended `Workflow-Test-Default.yml` and `Workflow-Test-WithManifest.yml` to run for fixture changes and verify the generated root index content. - Reused the existing `Build-PSModuleDocumentation.ps1` move logic; no generator change was required. - Implementation plan progress: completed the first slice for fully authored root indexes. Placeholder-driven generated submodule tables remain follow-up work. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `tests/**` (PowerShell fixtures) | Test fixture conventions | Process-PSModule test workflow | Aligned | | `.github/workflows/**` (GitHub Actions) | Workflow conventions | Process-PSModule documentation pipeline | Aligned | - Issue convergence sweep: reviewed #379; this PR delivers the authored-root-index slice only, while placeholder and generated-table behavior remains open. </details> <details> <summary>Relevant issues (or links)</summary> - #379 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 294e7b7 commit 10fc17b

5 files changed

Lines changed: 110 additions & 1 deletion

File tree

‎.github/workflows/Linter.yml‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,9 @@ name: Linter
22

33
run-name: "Linter - [${{ github.event.pull_request.title }} #${{ github.event.pull_request.number }}] by @${{ github.actor }}"
44

5-
on: [pull_request]
5+
on:
6+
pull_request:
7+
workflow_dispatch:
68

79
concurrency:
810
group: ${{ github.workflow }}-${{ github.ref }}
@@ -30,6 +32,7 @@ jobs:
3032
FILTER_REGEX_EXCLUDE: 'tests/src(TestRepo|WithManifestTestRepo)/src/classes/public/.*\.ps1$'
3133
VALIDATE_BIOME_FORMAT: false
3234
VALIDATE_GITHUB_ACTIONS: false
35+
VALIDATE_GITHUB_ACTIONS_ZIZMOR: false
3336
VALIDATE_JSCPD: false
3437
VALIDATE_JSON_PRETTIER: false
3538
VALIDATE_MARKDOWN_PRETTIER: false

‎.github/workflows/Workflow-Test-Default.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ on:
88
paths:
99
- '.github/actions/**'
1010
- '.github/workflows/**'
11+
- 'tests/srcTestRepo/**'
1112
- '!.github/workflows/Release.yml'
1213
- '!.github/workflows/Linter.yml'
1314
schedule:
@@ -46,3 +47,46 @@ jobs:
4647
^README\.md$
4748
^\.github/actions/
4849
^\.github/workflows/(?!Release\.yml$|Linter\.yml$)
50+
51+
VerifyRootFunctionsIndexDefault:
52+
name: Verify root Functions index [Default]
53+
runs-on: ubuntu-latest
54+
needs:
55+
- WorkflowTestDefault
56+
steps:
57+
- name: Checkout repo
58+
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
59+
with:
60+
persist-credentials: false
61+
fetch-depth: 0
62+
63+
- name: Download docs artifact
64+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
65+
with:
66+
name: docs
67+
path: tests/srcTestRepo/outputs/docs
68+
69+
- name: Verify root Functions index is published
70+
shell: pwsh
71+
run: |
72+
$path = 'tests/srcTestRepo/outputs/docs/index.md'
73+
if (-not (Test-Path -Path $path)) {
74+
throw 'Expected root Functions index at ' +
75+
'tests/srcTestRepo/outputs/docs/index.md.'
76+
}
77+
78+
$content = Get-Content -Path $path -Raw
79+
$expectedSnippets = @(
80+
'# Functions'
81+
'This landing page is authored from the root of ' +
82+
'`src/functions/public`.'
83+
'Use it to introduce the module''s function surface ' +
84+
'before readers drill into each group.'
85+
)
86+
87+
foreach ($snippet in $expectedSnippets) {
88+
if (-not $content.Contains($snippet)) {
89+
throw 'Expected snippet not found in generated root ' +
90+
"Functions index: $snippet"
91+
}
92+
}

‎.github/workflows/Workflow-Test-WithManifest.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ on:
88
paths:
99
- '.github/actions/**'
1010
- '.github/workflows/**'
11+
- 'tests/srcWithManifestTestRepo/**'
1112
- '!.github/workflows/Release.yml'
1213
- '!.github/workflows/Linter.yml'
1314
schedule:
@@ -46,3 +47,46 @@ jobs:
4647
^README\.md$
4748
^\.github/actions/
4849
^\.github/workflows/(?!Release\.yml$|Linter\.yml$)
50+
51+
VerifyRootFunctionsIndexWithManifest:
52+
name: Verify root Functions index [WithManifest]
53+
runs-on: ubuntu-latest
54+
needs:
55+
- WorkflowTestWithManifest
56+
steps:
57+
- name: Checkout repo
58+
uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
59+
with:
60+
persist-credentials: false
61+
fetch-depth: 0
62+
63+
- name: Download docs artifact
64+
uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c
65+
with:
66+
name: docs
67+
path: tests/srcWithManifestTestRepo/outputs/docs
68+
69+
- name: Verify root Functions index is published
70+
shell: pwsh
71+
run: |
72+
$path = 'tests/srcWithManifestTestRepo/outputs/docs/index.md'
73+
if (-not (Test-Path -Path $path)) {
74+
throw 'Expected root Functions index at ' +
75+
'tests/srcWithManifestTestRepo/outputs/docs/index.md.'
76+
}
77+
78+
$content = Get-Content -Path $path -Raw
79+
$expectedSnippets = @(
80+
'# Functions'
81+
'This landing page is authored from the root of ' +
82+
'`src/functions/public`.'
83+
'Use it to introduce the module''s function surface ' +
84+
'before readers drill into each group.'
85+
)
86+
87+
foreach ($snippet in $expectedSnippets) {
88+
if (-not $content.Contains($snippet)) {
89+
throw 'Expected snippet not found in generated root ' +
90+
"Functions index: $snippet"
91+
}
92+
}

‎tests/srcTestRepo/src/functions/public/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: A fully authored landing page for the exported function surface.
3+
---
4+
5+
# Functions
6+
7+
This landing page is authored from the root of `src/functions/public`.
8+
9+
Use it to introduce the module's function surface before readers drill into each group.

‎tests/srcWithManifestTestRepo/src/functions/public/index.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
description: A fully authored landing page for the exported function surface.
3+
---
4+
5+
# Functions
6+
7+
This landing page is authored from the root of `src/functions/public`.
8+
9+
Use it to introduce the module's function surface before readers drill into each group.

0 commit comments

Comments
 (0)