Skip to content

Commit 3fe63fb

Browse files
openshift-merge-bot[bot]openshift-merge-bot[bot]
authored
Merge pull request #188 from Kuadrant/181-remove-dangling-docs
removing glob imports, added script to detect dangling imports
2 parents df183be + a0c3b1f commit 3fe63fb

File tree

3 files changed

+166
-42
lines changed

3 files changed

+166
-42
lines changed

‎docs/install-olm.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -604,7 +604,7 @@ kubectl apply -k config/observability/openshift/grafana
604604
Create the example dashboards in Grafana
605605

606606
```bash
607-
kubectl apply -k https://github.com/Kuadrant/kuadrant-operator//examples/dashboards?ref=v1.0.1
607+
kubectl apply -k https://github.com/Kuadrant/kuadrant-operator/examples/dashboards?ref=v1.0.1
608608
```
609609

610610
Access the Grafana UI, using the default user/pass of root/secret.

‎mkdocs.yml

+77-41
Original file line numberDiff line numberDiff line change
@@ -52,59 +52,95 @@ plugins:
5252
css_dir: css
5353
javascript_dir: js
5454
- search
55+
# Note: Try to avoid globs for `imports`. Be explicit about imports, so we can avoid having
56+
# published dangling docs with no routes to them from the nav/other pages - these will go stale quickly.
5557
- multirepo:
5658
cleanup: true
5759
keep_docs_dir: true
5860
nav_repos:
5961
- name: kuadrant-operator
60-
import_url: 'https://github.com/kuadrant/kuadrant-operator?edit_uri=/blob/main/&branch=main'
62+
import_url: https://github.com/kuadrant/kuadrant-operator?edit_uri=/blob/main/&branch=main
6163
imports:
62-
- /README.md
63-
- /doc/*
64-
- /config/samples/*
65-
- /examples/*
64+
- /doc/install/mtls-configuration.md
65+
- /doc/observability/examples.md
66+
- /doc/observability/metrics.md
67+
- /doc/observability/tracing.md
68+
- /doc/overviews/auth.md
69+
- /doc/overviews/dns.md
70+
- /doc/overviews/rate-limiting.md
71+
- /doc/overviews/tls.md
72+
- /doc/reference/authpolicy.md
73+
- /doc/reference/dnspolicy.md
74+
- /doc/reference/kuadrant.md
75+
- /doc/reference/ratelimitpolicy.md
76+
- /doc/reference/tlspolicy.md
77+
- /doc/user-guides/auth/auth-for-app-devs-and-platform-engineers.md
78+
- /doc/user-guides/dns/basic-dns-configuration.md
79+
- /doc/user-guides/dns/dnshealthchecks.md
80+
- /doc/user-guides/dns/gateway-dns.md
81+
- /doc/user-guides/dns/load-balanced-dns.md
82+
- /doc/user-guides/full-walkthrough/secure-protect-connect.md
83+
- /doc/user-guides/ratelimiting/authenticated-rl-for-app-developers.md
84+
- /doc/user-guides/ratelimiting/authenticated-rl-with-jwt-and-k8s-authnz.md
85+
- /doc/user-guides/ratelimiting/gateway-rl-for-cluster-operators.md
86+
- /doc/user-guides/ratelimiting/multi-auth-rlp-diff-section.md
87+
- /doc/user-guides/ratelimiting/multi-auth-rlp-same-section.md
88+
- /doc/user-guides/tls/gateway-tls.md
89+
- /doc/observability/grafana_trace.png
90+
- /doc/observability/grafana_tracing_loki.png
91+
- /doc/user-guides/ratelimiting/simple-rl-for-app-developers.md
6692
- name: authorino
67-
import_url: 'https://github.com/kuadrant/authorino?edit_uri=/blob/main/&branch=main'
93+
import_url: https://github.com/kuadrant/authorino?edit_uri=/blob/main/&branch=main
6894
imports:
69-
- /README.md
70-
- /docs/*
71-
- /docs/user-guides/*
72-
- /install/crd/*
73-
- name: authorino-operator
74-
import_url: 'https://github.com/kuadrant/authorino-operator?edit_uri=/blob/main/&branch=main'
75-
imports:
76-
- /README.md
77-
- name: limitador
78-
import_url: 'https://github.com/kuadrant/limitador?edit_uri=/blob/main/&branch=main'
79-
imports:
80-
- /README.md
81-
- /doc/*
82-
- /limitador-server/README.md
83-
- /limitador-server/docs/*
84-
- /limitador/README.md
85-
- /limitador-server/kubernetes/*
86-
- /limitador-server/sandbox/*
87-
- /LICENSE
88-
- name: limitador-operator
89-
import_url: 'https://github.com/kuadrant/limitador-operator?edit_uri=/blob/main/&branch=main'
90-
imports:
91-
- /README.md
92-
- /doc/*
95+
- /docs/user-guides/observability.md
96+
- /docs/features.md
97+
- /docs/architecture.md
98+
- /docs/architecture.gif
99+
- /docs/auth-pipeline.gif
100+
- /install/crd/*
101+
- /docs/user-guides.md
102+
- /docs/user-guides/*
103+
- /docs/user-guides/hello-world.md
104+
- /docs/user-guides/anonymous-access.md
105+
- /docs/user-guides/oidc-user-info.md
106+
- /docs/user-guides/oidc-rbac.md
107+
- /docs/user-guides/authzed.md
108+
- /docs/user-guides/injecting-data.md
109+
- /docs/user-guides/host-override.md
110+
- /docs/user-guides/sharding.md
111+
- /docs/user-guides/caching.md
112+
- /docs/user-guides/sharding.md
113+
- /docs/getting-started.md
114+
- /docs/user-guides/api-key-authentication.md
115+
- /docs/user-guides/authenticated-rate-limiting-envoy-dynamic-metadata.md
116+
- /docs/user-guides/deny-with-redirect-to-login.md
117+
- /docs/user-guides/edge-authentication-architecture-festival-wristbands.md
118+
- /docs/user-guides/envoy-jwt-authn-and-authorino.md
119+
- /docs/user-guides/external-metadata.md
120+
- /docs/user-guides/http-basic-authentication.md
121+
- /docs/user-guides/json-pattern-matching-authorization.md
122+
- /docs/user-guides/keycloak-authorization-services.md
123+
- /docs/user-guides/kubernetes-subjectaccessreview.md
124+
- /docs/user-guides/kubernetes-tokenreview.md
125+
- /docs/user-guides/mtls-authentication.md
126+
- /docs/user-guides/oauth2-token-introspection.md
127+
- /docs/user-guides/oidc-jwt-authentication.md
128+
- /docs/user-guides/opa-authorization.md
129+
- /docs/user-guides/passing-credentials.md
130+
- /docs/user-guides/resource-level-authorization-uma.md
131+
- /docs/user-guides/token-normalization.md
132+
- /docs/terminology.md
133+
- /docs/contributing.md
134+
- /docs/README.md
93135
- name: architecture
94-
import_url: 'https://github.com/kuadrant/architecture?edit_uri=/blob/main/&branch=main'
95-
imports:
96-
- /docs/design/*
97-
- name: kuadrantctl
98-
import_url: 'https://github.com/kuadrant/kuadrantctl?edit_uri=/blob/main/&branch=main'
136+
import_url: https://github.com/kuadrant/architecture?edit_uri=/blob/main/&branch=main
99137
imports:
100-
- /README.md
101-
- /doc/*
138+
- /docs/design/architectural-overview-v1.md
139+
- /docs/design/images/*
102140
- name: dns-operator
103-
import_url: 'https://github.com/kuadrant/dns-operator?edit_uri=/blob/main/&branch=main'
141+
import_url: https://github.com/kuadrant/dns-operator?edit_uri=/blob/main/&branch=main
104142
imports:
105-
- /README.md
106-
- /docs/*
107-
- /config/samples/*
143+
- /docs/provider.md
108144
- redirects:
109145
redirect_maps:
110146
'getting-started-single-cluster.md': 'getting-started.md'

‎validate_imports.py

+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Helper script to generate explicit imports for the multirepo plugin from the nav
2+
# Note: this will not find certain kinds of links, e.g. images or links between docs - so you'll still need to do a bit of manual work to generate imports.
3+
# The list if imports it produces will not be exhaustive. Re run `mkdocs -s` to find other, missing imports
4+
5+
import yaml
6+
7+
def generate_explicit_nav_repos(mkdocs_file):
8+
with open(mkdocs_file, 'r') as f:
9+
raw_content = f.read()
10+
11+
# Preprocess to remove problematic syntax (e.g., !!python/name)
12+
sanitized_content = clean(raw_content)
13+
config = yaml.safe_load(sanitized_content)
14+
15+
# Extract files from nav
16+
nav_files = set(extract_files_from_nav(config['nav']))
17+
18+
# Build new multirepo imports
19+
explicit_imports = generate_imports(config['plugins'], nav_files)
20+
21+
print("Updated nav_repos:")
22+
print(yaml.dump(explicit_imports, default_flow_style=False, sort_keys=False))
23+
24+
def clean(content):
25+
return "\n".join([line for line in content.splitlines() if '!!python/name:' not in line])
26+
27+
def extract_files_from_nav(nav):
28+
files = []
29+
for item in nav:
30+
if isinstance(item, dict):
31+
for key, value in item.items():
32+
if isinstance(value, list):
33+
files.extend(extract_files_from_nav(value))
34+
else:
35+
files.append(value)
36+
else:
37+
files.append(item)
38+
return files
39+
40+
def generate_imports(plugins, nav_files):
41+
new_imports = []
42+
for plugin in plugins:
43+
if isinstance(plugin, dict) and 'multirepo' in plugin:
44+
for repo in plugin['multirepo']['nav_repos']:
45+
repo_name = repo['name']
46+
repo_import_url = repo['import_url']
47+
repo_explicit_imports = []
48+
49+
for pattern in repo['imports']:
50+
matching_files = match_files_to_pattern(nav_files, pattern, repo_name)
51+
52+
repo_explicit_imports.extend(
53+
add_leading_slash(remove_repo_name_prefix(matching_files, repo_name))
54+
)
55+
56+
# Deduplicate imports (may be used multiple times in nav)
57+
repo_explicit_imports = sorted(set(repo_explicit_imports))
58+
59+
new_imports.append({
60+
'name': repo_name,
61+
'import_url': repo_import_url,
62+
'imports': repo_explicit_imports,
63+
})
64+
return new_imports
65+
66+
def match_files_to_pattern(nav_files, pattern, repo_name):
67+
base_path = f"{repo_name}/"
68+
if pattern.startswith('/'):
69+
pattern = pattern[1:] # Remove leading slash
70+
if '*' in pattern or '?' in pattern:
71+
# Handle glob patterns
72+
prefix = base_path + pattern.split('*')[0]
73+
return {file for file in nav_files if file.startswith(prefix)}
74+
else:
75+
# Handle exact matches
76+
expected_path = base_path + pattern.lstrip('/')
77+
return {file for file in nav_files if file == expected_path}
78+
79+
def remove_repo_name_prefix(files, repo_name):
80+
# Remove the repo name prefix from file paths
81+
prefix = f"{repo_name}/"
82+
return [file[len(prefix):] for file in files if file.startswith(prefix)]
83+
84+
def add_leading_slash(files):
85+
return [f"/{file}" if not file.startswith("/") else file for file in files]
86+
87+
# Run
88+
generate_explicit_nav_repos('mkdocs.yml')

0 commit comments

Comments
 (0)