Skip to content

Commit 5c85fde

Browse files
Improve link checking for our docs (#3022)
* Switch to using htmltest * Use relref function for page links * Fix image links * Fix external references * Fix charts reference * Code Gardening * Remove markdown-link-check * Document use of private fork
1 parent ad02e47 commit 5c85fde

30 files changed

+83
-142
lines changed

.devcontainer/install-dependencies.sh

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,8 @@ go-install kustomize sigs.k8s.io/kustomize/kustomize/[email protected]
150150

151151
# for docs site
152152
go-install hugo -tags extended github.com/gohugoio/[email protected]
153-
go-install htmltest github.com/wjdp/[email protected]
153+
# Restore this to github.com/wjdp/htmltest@v?? once PR#215 is merged with the feature we need
154+
go-install htmltest github.com/theunrepentantgeek/htmltest@latest
154155

155156
# for api docs
156157
# TODO: Replace this with the new release tag.
@@ -220,15 +221,7 @@ fi
220221
write-verbose "Checking for /usr/bin/postcss"
221222
if should-install "/usr/bin/postcss"; then
222223
write-info "Installing postcss"
223-
sudo npm install -g postcss postcss-cli autoprefixer
224-
fi
225-
226-
# Ensure we can check links
227-
write-verbose "Checking for /usr/bin/markdown-link-check"
228-
if should-install "/usr/bin/markdown-link-check"; then
229-
write-info "Installing markdown-link-check"
230-
# Pinned to 3.10 due to https://github.com/tcort/markdown-link-check/issues/246
231-
sudo npm install -g [email protected]
224+
npm install --global postcss postcss-cli autoprefixer
232225
fi
233226

234227
if [ "$VERBOSE" == true ]; then

.github/workflows/deploy-site.yml

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,6 @@ jobs:
5454
- name: Build & validate docs site
5555
run: |
5656
container_id=${{ env.container_id }}
57-
docker exec "$container_id" task check-docs-site-links
5857
docker exec "$container_id" task build-docs-site
5958
6059
- name: Publish to gh-pages branch

.github/workflows/pr-validation-docs.yml

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -62,11 +62,6 @@ jobs:
6262
docker start "$container_id"
6363
echo "container_id=$container_id" >> $GITHUB_ENV
6464
65-
- name: Validate docs site
66-
run: |
67-
container_id=${{ env.container_id }}
68-
docker exec "$container_id" task check-docs-site-links
69-
7065
- name: Build & validate docs site
7166
run: |
7267
container_id=${{ env.container_id }}

Taskfile.yml

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -89,21 +89,8 @@ tasks:
8989
build-docs-site:
9090
dir: docs/hugo
9191
cmds:
92-
- npm install -g postcss postcss-cli autoprefixer
9392
- hugo
94-
# - htmltest
95-
# disabled pending: https://github.com/wjdp/htmltest/issues/45
96-
# , or us moving to a no-directory URL
97-
env:
98-
NODE_PATH:
99-
sh: npm root -g
100-
101-
check-docs-site-links:
102-
desc: Verify documentation site links
103-
dir: docs/hugo
104-
cmds:
105-
# Excluding './content/reference/*' path as it contains all auto-generated API docs.
106-
- find . -type f -name "*.md" -not -path "./content/reference/*" -not -path "./node_modules/*" -print0 | xargs -0 -n1 markdown-link-check -c link-checker.json
93+
- htmltest
10794
env:
10895
NODE_PATH:
10996
sh: npm root -g

docs/hugo/.htmltest.yml

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
11
DirectoryPath: public
2-
CheckExternal: false
2+
CheckExternal: true
33
IgnoreAltMissing: true
4+
BaseURL: https://azure.github.io/azure-service-operator
5+
CheckSelfReferencesAsInternal: true
6+
IgnoreDirs:
7+
- "reference" # Ignore errors in CRD docs, content is not under our control
8+
IgnoreURLs:
9+
- /favicons/
10+
- /scss/
11+
- /js/
12+
- example.com
13+
- index.xml
14+
- "https://armwiki.azurewebsites.net/api_contracts/guidelines/templatedeployment.html" # Returns 404 even though valid
15+
- "https://marketplace.visualstudio.com/items" # Marketplace links return 401 even if valid
16+
- "https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md" # Manually checked, not a 404
17+
- "azure-workload-identity" # TODO: Work out why this fails
18+
LogLevel: 3

docs/hugo/content/contributing/_index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@ description: "How to contribute new resources to Azure Service Operator v2"
1313

1414
## Related pages
1515

16-
* [Adding a new code-generator resource](./add-a-new-code-generated-resource).
17-
* [Generator code overview](./generator-overview)
16+
* [Adding a new code-generator resource]( {{< relref "add-a-new-code-generated-resource" >}} ).
17+
* [Generator code overview]( {{< relref "generator-overview" >}} )
1818

1919
## Developer setup (with VS Code)
2020
This is the recommended setup, especially if you are using Windows as your development platform.

docs/hugo/content/contributing/add-a-new-code-generated-resource.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ configuration around the existing values.
7474
7575
## Run the code generator
7676
77-
Follow the steps in the [contributing guide](_index.md) to set up your development environment.
77+
Follow the steps in the [contributing guide]( {{< relref "." >}} ) to set up your development environment.
7878
Once you have a working development environment, run the `task` command to run the code generator.
7979

8080
## Fix any errors raised by the code generator

docs/hugo/content/design/ADR-2021-06-API-Version-Recovery.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,9 @@ title: '2021-06: API Version Recovery'
66

77
In addition to structural changes, there may be behaviour changes between ARM API versions. It is therefore important that we use the correct API version - the version requested by the user - when interacting with ARM, to ensure that we get the expected behaviour.
88

9-
Revisting the CRM example from the [Versioning](../versioning/) specification, consider what happens if we have two available versions of the resource `Person`, lets call them **v1** and **v2**. In **v2** the new properties `PostalAddress` and `ResidentialAddress` are mandatory, requiring that everyone have a both a mailing address and a home.
9+
Revisting the CRM example from the [Versioning]( {{< relref "versioning" >}} ) specification, consider what happens if we have two available versions of the resource `Person`, lets call them **v1** and **v2**. In **v2** the new properties `PostalAddress` and `ResidentialAddress` are mandatory, requiring that everyone have a both a mailing address and a home.
1010

11-
![example](images/adr-2021-06-api-version-recovery-example.png)
11+
![example](../images/adr-2021-06-api-version-recovery-example.png)
1212

1313
If we have a valid **v1** `Person`, trying to submit that through the **v2** ARM API will fail because it's missing these addresses.
1414

@@ -53,7 +53,7 @@ type StorageAccounts_Spec struct {
5353
}
5454
```
5555

56-
![preservation](images/adr-2021-06-api-version-recovery-preservation.png)
56+
![preservation](../images/adr-2021-06-api-version-recovery-preservation.png)
5757

5858
The generated `AssignProperties*()` methods will copy OriginalVersion as expected.
5959

docs/hugo/content/design/ADR-2022-02-Backward-Compatibility.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,13 +102,13 @@ Introduce a new pipeline stage to create additional versions for backward compat
102102

103103
For example, the API resource `v1beta20201201storage/VirtualMachine` will be cloned as `v1alpha1api20201201/VirtualMachine`. Subsequent pipeline stages will create matching storage versions and the necessary conversions.
104104

105-
![image](images/adr-2022-02-backward-compatibility-single-version.png)
105+
![image](../images/adr-2022-02-backward-compatibility-single-version.png)
106106

107107
For the trivial case where we only support a single ARM version of a resource, this gives us full compatibility to upgrade an older (alpha) installation of ASO to a new beta release.
108108

109109
When we have multiple ARM versions in flight (as we do with `compute`), supporting all *potential* older resource versions gives us maximum compatibility without any need for configuration or to make any assumptions about which ARM versions were previously supported.
110110

111-
![image](images/adr-2022-02-backward-compatibility-multiple-version.png)
111+
![image](../images/adr-2022-02-backward-compatibility-multiple-version.png)
112112

113113
This approach also gives us backward compatibility when we have a mix of resources across multiple versions (as happens with both `compute` and `network`). We know from prior work (including introduction of the `PropertyBag` field) that conversions between storage versions are lossless.
114114

docs/hugo/content/design/ADR-2022-09-Multiple-Credential-Operator.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ To support this, ASO will introduce support for multiple credentials, each assoc
1919

2020
We'll be using a pattern to determine which of the above secrets we use for operation on a resource. As in the below flow chart, if a resource is applied to the operator and the resource exists, operator would fetch and apply credentials in a following manner. If it's a new resource, operator would have to go through the secret selection hierarchy. Where, operator would first check if Per-resource or per-resource-group secret exists, if not, then will check for the namespaced secret. If any of the above is provided, operator would perform actions according to the **options** below. If none is provided, we'll fallback to use the global credential for that resource, which is the default cluster scoped secret(aso-controller-settings) in ASO namespace used today.
2121

22-
![hierarchy](images/adr-2022-09-multiple-credential-operator.png)
22+
![hierarchy](../images/adr-2022-09-multiple-credential-operator.png)
2323

2424
## Options
2525

docs/hugo/content/design/ADR-2022-12-Reconciliation-Extensions.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,11 +46,11 @@ The return will be one of three possibilities:
4646

4747
For the initial implementation, we'll only do the GET if the extension exists, and the default `next` action will be hard coded to request a reconciliation.
4848

49-
![Initial Sequence](images/adr-2022-12-reconciliation-initial-flow.png)
49+
![Initial Sequence](../images/adr-2022-12-reconciliation-initial-flow.png)
5050

5151
Down the track when we switch to a GET/PUT workflow, we'll always do the GET, and the default 'next` action will do the comparison to see if the resource has changed.
5252

53-
![GET/PUT Sequence](images/adr-2022-12-reconciliation-diffing-flow.png)
53+
![GET/PUT Sequence](../images/adr-2022-12-reconciliation-diffing-flow.png)
5454

5555
## Status
5656

docs/hugo/content/design/ADR-2023-05-Installing-Only-Selected-CRDs.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ pre-install hook (or post-install) seems easier though.
152152

153153
#### Answer 2c: Using a CRD
154154

155-
We investigated doing this originally for [Helm chart size limitations](../ADR-2023-02-Helm-Chart-Size-Limitations)
155+
We investigated doing this originally for [Helm chart size limitations]( {{< relref "ADR-2023-02-Helm-Chart-Size-Limitations" >}} )
156156

157157
Pros:
158158
* More structured than a `ConfigMap`.

docs/hugo/content/design/secrets.md

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -325,9 +325,7 @@ the right `ListKeys` or `GetKeys` call. To support rollover we would need a diff
325325
This is a relatively involved topic so not designing it all here. As a starting point, resources manually implementing the following interface would
326326
get us what we need. Issue [#1978](https://github.com/Azure/azure-service-operator/issues/1978) is tracking this request in more detail.
327327

328-
<!-- Link check fails because Hugo transforms the filename to lowercase. Manually checked by @theunrepentantgeek -->
329-
<!-- markdown-link-check-disable-next-line -->
330-
See also the design of [reconciler extensions](../adr-2022-01-reconciler-extensions).
328+
See also the design of [reconciler extensions]( {{< relref "adr-2022-01-reconciler-extensions" >}} ).
331329

332330
```go
333331
type ARMDetails struct {

docs/hugo/content/design/versioning/_index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,11 +35,11 @@ Unlike the typical situation with a hand written service operator, we don't have
3535

3636
There are three case studies that accompany this specification, each one walking through one possible solution and showing how it will perform as a synthetic ARM style API evolves over time.
3737

38-
The [**Chained Versions**](../case-studies/chained-storage-versions/) case study shows how the preferred solution adapts to changes as the API is modified.
38+
The [**Chained Versions**]( {{< relref "case-studies/chained-storage-versions" >}} ) case study shows how the preferred solution adapts to changes as the API is modified.
3939

40-
The [**Rolling Versions**](../case-studies/rolling-storage-versions/) case study shows an alternative that works well but falls down when hand coded conversions are introduced between versions.
40+
The [**Rolling Versions**]( {{< relref "case-studies/rolling-storage-versions" >}} ) case study shows an alternative that works well but falls down when hand coded conversions are introduced between versions.
4141

42-
The [**Fixed Version**](../case-studies/fixed-storage-version/) case study shows how a popular alternative would fare, calling out some specific problems that will occur.
42+
The [**Fixed Version**]( {{< relref "case-studies/fixed-storage-version" >}} ) case study shows how a popular alternative would fare, calling out some specific problems that will occur.
4343

4444
**TL;DR:** Using a *fixed storage version* appears simpler at first, and works well as long as the changes from version to version are simple. However, when the changes become complex (as they are bound to do over time), this approach starts to break down. While there is up front complexity to address with *chained storage versions*, the approach doesn't break down over time and we can generate useful automated tests for verification. The *rolling storage version* approach is viable, but requires additional ongoing maintenance when manual conversions are introduced between versions.
4545

docs/hugo/content/guide/annotations.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ This credential supersedes any global or namespace scoped credentials the operat
2929
Allow values are:
3030
- The name of any secret in the same namespace as the resource. Secrets from other namespaces cannot be referenced.
3131

32-
See [authentication](./authentication/_index.md#credential-scope) for more details.
32+
See [authentication]( {{< relref "authentication#credential-scope" >}} ) for more details.
3333

3434
## Annotations written by the operator
3535

docs/hugo/content/guide/aso-controller-settings-options.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ The supported options are:
1313
### AZURE_SUBSCRIPTION_ID
1414

1515
Azure subscription the operator will use for ARM communication if
16-
no [more specific](authentication/credential-scope)
16+
no [more specific]( {{< relref "authentication/credential-scope" >}} )
1717
credential is specified at the per-resource or per-namespace scope.
1818

1919
**Format:** `GUID`
@@ -27,7 +27,7 @@ This may be set to empty string to configure no global credential.
2727
### AZURE_TENANT_ID
2828

2929
Azure tenantID the operator will use for ARM communication if
30-
no [more specific](authentication/credential-scope)
30+
no [more specific]( {{< relref "authentication/credential-scope" >}} )
3131
credential is specified at the per-resource or per-namespace scope.
3232

3333
**Format:** `GUID`
@@ -41,7 +41,7 @@ This may be set to empty string to configure no global credential.
4141
### AZURE_CLIENT_ID
4242

4343
Azure clientID the operator will use for ARM communication if
44-
no [more specific](authentication/credential-scope)
44+
no [more specific]( {{< relref "authentication/credential-scope" >}} )
4545
credential is specified at the per-resource or per-namespace scope.
4646

4747
**Format:** `GUID`
@@ -55,7 +55,7 @@ This may be set to empty string to configure no global credential.
5555
### AZURE_CLIENT_SECRET
5656

5757
The secret associated with the client to use if
58-
no [more specific](authentication/credential-scope)
58+
no [more specific]( {{< relref "authentication/credential-scope" >}} )
5959
credential is specified at the per-resource or per-namespace scope.
6060

6161
**Format:** `String`

docs/hugo/content/guide/authentication/_index.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,18 +13,18 @@ There are two key topics surrounding authentication in Azure Service Operator: T
1313

1414
Azure Service Operator supports four different styles of authentication today.
1515

16-
1. [Service Principal using a Client Secret](./credential-format#service-principal-using-a-client-secret)
17-
2. [Service Principal using a Client Certificate](./credential-format#service-principal-using-a-client-certificate)
18-
3. [Azure-Workload-Identity authentication](./credential-format#azure-workload-identity) (OIDC + Managed Identity or Service Principal)
19-
4. [Deprecated] [aad-pod-identity authentication (Managed Identity)](./credential-format#deprecated-managed-identity--aad-pod-identity-)
16+
1. [Service Principal using a Client Secret]( {{< relref "credential-format#service-principal-using-a-client-secret" >}} )
17+
2. [Service Principal using a Client Certificate]( {{< relref "credential-format#service-principal-using-a-client-certificate" >}} )
18+
3. [Azure-Workload-Identity authentication]( {{< relref "credential-format#azure-workload-identity" >}} ) (OIDC + Managed Identity or Service Principal)
19+
4. [Deprecated] [aad-pod-identity authentication (Managed Identity)]( {{< relref "credential-format#deprecated-managed-identity-aad-pod-identity" >}} )
2020

2121
## Credential scope
2222

2323
Each supported credential type can be specified at one of three supported scopes:
2424

25-
1. [Global](./credential-scope#global-scope) - The credential applies to all resources managed by ASO.
26-
2. [Namespace](./credential-scope#namespace-scope) - The credential applies to all resources managed by ASO in that namespace.
27-
3. [Resource](./credential-scope#resource-scope) - The credential applies to only the specific resource it is referenced on.
25+
1. [Global]( {{< relref "credential-scope#global-scope" >}} ) - The credential applies to all resources managed by ASO.
26+
2. [Namespace]( {{< relref "credential-scope#namespace-scope" >}} ) - The credential applies to all resources managed by ASO in that namespace.
27+
3. [Resource]( {{< relref "credential-scope#resource-scope" >}} ) - The credential applies to only the specific resource it is referenced on.
2828

2929
When presented with multiple credential choices, the operator chooses the most specific one:
3030
_resource scope_ takes precedence over _namespace scope_ which takes precedence over _global scope_.
@@ -53,4 +53,4 @@ Disadvantages:
5353
* Significantly harder to orchestrate ASO upgrades.
5454
* More kube-apiserver load, as there will be multiple operators running and watching/reconciling resources.
5555

56-
For more details about this approach, see [multitenant deployment](./multitenant-deployment)
56+
For more details about this approach, see [multitenant deployment]( {{< relref "multitenant-deployment" >}} )

0 commit comments

Comments
 (0)