Skip to content

Commit e79ad4d

Browse files
EffortlessStevenEffortlessSteven
authored
Enforce docs/version snippet sync: extend metadata and tighten xtask docs-sync (#377)
* Strengthen docs-sync drift checks and snippet metadata * style(xtask): format docs-sync drift checks * style(xtask): format docs-sync test imports
1 parent 19e3058 commit e79ad4d

File tree

4 files changed

+621
-75
lines changed

4 files changed

+621
-75
lines changed

‎crates/uselesskey/README.md‎

Lines changed: 54 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,60 @@ like `Factory`, `Mode`, and `Seed`; enable only the fixture families you need.
3434

3535
Token-only consumers can stay lightweight:
3636

37-
```toml
38-
[dev-dependencies]
39-
uselesskey = { version = "0.5.1", default-features = false, features = ["token"] }
40-
```
37+
<!-- docs-sync:dependency-snippets-start -->
38+
Dependency snippets:
39+
- **Quick start (RSA)**
40+
```toml
41+
[dev-dependencies]
42+
uselesskey = { version = "0.5.1", features = ["rsa"] }
43+
```
44+
45+
46+
- **Token-only**
47+
```toml
48+
[dev-dependencies]
49+
uselesskey = { version = "0.5.1", default-features = false, features = ["token"] }
50+
```
51+
52+
53+
- **JWT/JWK**
54+
```toml
55+
[dev-dependencies]
56+
uselesskey = { version = "0.5.1", features = ["rsa", "jwk"] }
57+
```
58+
59+
60+
- **X.509 + rustls**
61+
```toml
62+
[dev-dependencies]
63+
uselesskey = { version = "0.5.1", features = ["x509"] }
64+
uselesskey-rustls = { version = "0.5.1", features = ["tls-config", "rustls-ring"] }
65+
```
66+
67+
68+
- **jsonwebtoken adapter**
69+
```toml
70+
[dev-dependencies]
71+
uselesskey = { version = "0.5.1", features = ["rsa", "ecdsa", "ed25519", "hmac"] }
72+
uselesskey-jsonwebtoken = { version = "0.5.1" }
73+
```
74+
75+
76+
- **JOSE/OpenID adapter**
77+
```toml
78+
[dev-dependencies]
79+
uselesskey = { version = "0.5.1", features = ["rsa", "ecdsa", "ed25519", "hmac"] }
80+
uselesskey-jose-openid = { version = "0.5.1" }
81+
```
82+
83+
84+
- **pgp-native adapter**
85+
```toml
86+
[dev-dependencies]
87+
uselesskey = { version = "0.5.1", features = ["pgp"] }
88+
uselesskey-pgp-native = { version = "0.5.1" }
89+
```
90+
<!-- docs-sync:dependency-snippets-end -->
4191

4292
```rust
4393
use uselesskey::{Factory, TokenFactoryExt, TokenSpec};

‎docs/how-to/choose-features.md‎

Lines changed: 63 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -12,10 +12,60 @@ Use this page when you are deciding which feature flags to enable first.
1212
- Add `hmac` for HS256/HS384/HS512 fixtures.
1313
- Add `pgp` for OpenPGP armored/binary artifacts.
1414

15-
```toml
16-
[dev-dependencies]
17-
uselesskey = { version = "0.5.1", features = ["rsa", "ecdsa", "ed25519", "hmac", "pgp"] }
18-
```
15+
<!-- docs-sync:dependency-snippets-start -->
16+
Dependency snippets:
17+
- **Quick start (RSA)**
18+
```toml
19+
[dev-dependencies]
20+
uselesskey = { version = "0.5.1", features = ["rsa"] }
21+
```
22+
23+
24+
- **Token-only**
25+
```toml
26+
[dev-dependencies]
27+
uselesskey = { version = "0.5.1", default-features = false, features = ["token"] }
28+
```
29+
30+
31+
- **JWT/JWK**
32+
```toml
33+
[dev-dependencies]
34+
uselesskey = { version = "0.5.1", features = ["rsa", "jwk"] }
35+
```
36+
37+
38+
- **X.509 + rustls**
39+
```toml
40+
[dev-dependencies]
41+
uselesskey = { version = "0.5.1", features = ["x509"] }
42+
uselesskey-rustls = { version = "0.5.1", features = ["tls-config", "rustls-ring"] }
43+
```
44+
45+
46+
- **jsonwebtoken adapter**
47+
```toml
48+
[dev-dependencies]
49+
uselesskey = { version = "0.5.1", features = ["rsa", "ecdsa", "ed25519", "hmac"] }
50+
uselesskey-jsonwebtoken = { version = "0.5.1" }
51+
```
52+
53+
54+
- **JOSE/OpenID adapter**
55+
```toml
56+
[dev-dependencies]
57+
uselesskey = { version = "0.5.1", features = ["rsa", "ecdsa", "ed25519", "hmac"] }
58+
uselesskey-jose-openid = { version = "0.5.1" }
59+
```
60+
61+
62+
- **pgp-native adapter**
63+
```toml
64+
[dev-dependencies]
65+
uselesskey = { version = "0.5.1", features = ["pgp"] }
66+
uselesskey-pgp-native = { version = "0.5.1" }
67+
```
68+
<!-- docs-sync:dependency-snippets-end -->
1969

2070
If you need every key family, use `all-keys`.
2171

@@ -24,34 +74,27 @@ If you need every key family, use `all-keys`.
2474
- Add `jwk` plus the key families you want represented in the JWK outputs.
2575
- Keep `jwk` off when all you need is PEM/DER/private-key text.
2676

27-
```toml
28-
[dev-dependencies]
29-
uselesskey = { version = "0.5.1", features = ["rsa", "jwk"] }
30-
```
31-
3277
## I need X.509 / TLS
3378

3479
- Add `x509` for self-signed certs and certificate chains.
3580
- Add `uselesskey-rustls` (with `tls-config`) when you need rustls-native config builders.
3681
- Add `uselesskey-tonic` when you need gRPC TLS examples.
3782

38-
```toml
39-
[dev-dependencies]
40-
uselesskey = { version = "0.5.1", features = ["x509"] }
41-
uselesskey-rustls = { version = "0.5.1", features = ["tls-config", "rustls-ring"] }
42-
```
43-
4483
## I need token shapes only
4584

4685
- Add `token` (and disable default features if you only want token fixtures).
4786

48-
```toml
49-
[dev-dependencies]
50-
uselesskey = { version = "0.5.1", default-features = false, features = ["token"] }
51-
```
87+
## Minimal runnable commands
88+
89+
<!-- docs-sync:minimal-example-commands-start -->
90+
| Scenario | Minimal command | Description |
91+
|----------|------------------|-------------|
92+
| RSA + JWK | `cargo run -p uselesskey --example basic_rsa --no-default-features --features rsa,jwk` | Generate RSA fixtures and JWK output. |
93+
| Token fixtures | `cargo run -p uselesskey --example token_generation --no-default-features --features token` | Emit API key and bearer/OAuth token shapes. |
94+
| X.509 + rustls | `cargo run -p uselesskey --example adapter_rustls --no-default-features --features x509` | Build rustls configs from generated cert fixtures. |
95+
<!-- docs-sync:minimal-example-commands-end -->
5296

5397
## When you want fewer dependencies
5498

5599
- Prefer the facade for speed and convenience.
56100
- Prefer direct leaf crates when dependency shape is more important than convenience.
57-

‎docs/metadata/workspace-docs.json‎

Lines changed: 156 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -867,31 +867,180 @@
867867
"dependency_snippets": [
868868
{
869869
"name": "Quick start (RSA)",
870-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"rsa\"] }"
870+
"dependencies": [
871+
{
872+
"crate_name": "uselesskey",
873+
"default_features": null,
874+
"features": [
875+
"rsa"
876+
]
877+
}
878+
],
879+
"minimal_example_command": "cargo run -p uselesskey --example basic_rsa --no-default-features --features rsa,jwk"
871880
},
872881
{
873882
"name": "Token-only",
874-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", default-features = false, features = [\"token\"] }"
883+
"dependencies": [
884+
{
885+
"crate_name": "uselesskey",
886+
"default_features": false,
887+
"features": [
888+
"token"
889+
]
890+
}
891+
],
892+
"minimal_example_command": "cargo run -p uselesskey --example token_generation --no-default-features --features token"
875893
},
876894
{
877895
"name": "JWT/JWK",
878-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"rsa\", \"jwk\"] }"
896+
"dependencies": [
897+
{
898+
"crate_name": "uselesskey",
899+
"default_features": null,
900+
"features": [
901+
"rsa",
902+
"jwk"
903+
]
904+
}
905+
],
906+
"minimal_example_command": "cargo run -p uselesskey --example jwt_rs256_jwks --no-default-features --features rsa,jwk"
879907
},
880908
{
881909
"name": "X.509 + rustls",
882-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"x509\"] }\nuselesskey-rustls = { version = \"0.5.1\", features = [\"tls-config\", \"rustls-ring\"] }"
910+
"dependencies": [
911+
{
912+
"crate_name": "uselesskey",
913+
"default_features": null,
914+
"features": [
915+
"x509"
916+
]
917+
},
918+
{
919+
"crate_name": "uselesskey-rustls",
920+
"default_features": null,
921+
"features": [
922+
"tls-config",
923+
"rustls-ring"
924+
]
925+
}
926+
],
927+
"minimal_example_command": "cargo run -p uselesskey --example adapter_rustls --no-default-features --features x509"
883928
},
884929
{
885930
"name": "jsonwebtoken adapter",
886-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"rsa\", \"ecdsa\", \"ed25519\", \"hmac\"] }\nuselesskey-jsonwebtoken = { version = \"0.5.1\" }"
931+
"dependencies": [
932+
{
933+
"crate_name": "uselesskey",
934+
"default_features": null,
935+
"features": [
936+
"rsa",
937+
"ecdsa",
938+
"ed25519",
939+
"hmac"
940+
]
941+
},
942+
{
943+
"crate_name": "uselesskey-jsonwebtoken",
944+
"default_features": null,
945+
"features": []
946+
}
947+
],
948+
"minimal_example_command": "cargo run -p uselesskey --example adapter_jsonwebtoken --no-default-features --features rsa,ecdsa,ed25519,hmac"
887949
},
888950
{
889951
"name": "JOSE/OpenID adapter",
890-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"rsa\", \"ecdsa\", \"ed25519\", \"hmac\"] }\nuselesskey-jose-openid = { version = \"0.5.1\" }"
952+
"dependencies": [
953+
{
954+
"crate_name": "uselesskey",
955+
"default_features": null,
956+
"features": [
957+
"rsa",
958+
"ecdsa",
959+
"ed25519",
960+
"hmac"
961+
]
962+
},
963+
{
964+
"crate_name": "uselesskey-jose-openid",
965+
"default_features": null,
966+
"features": []
967+
}
968+
],
969+
"minimal_example_command": "cargo test -p uselesskey-jose-openid --no-default-features --features rsa"
891970
},
892971
{
893972
"name": "pgp-native adapter",
894-
"snippet": "[dev-dependencies]\nuselesskey = { version = \"0.5.1\", features = [\"pgp\"] }\nuselesskey-pgp-native = { version = \"0.5.1\" }"
973+
"dependencies": [
974+
{
975+
"crate_name": "uselesskey",
976+
"default_features": null,
977+
"features": [
978+
"pgp"
979+
]
980+
},
981+
{
982+
"crate_name": "uselesskey-pgp-native",
983+
"default_features": null,
984+
"features": []
985+
}
986+
],
987+
"minimal_example_command": "cargo test -p uselesskey-pgp-native --no-default-features --features rsa"
988+
}
989+
],
990+
"release_version": "0.5.1",
991+
"public_features": [
992+
"rsa",
993+
"ecdsa",
994+
"ed25519",
995+
"hmac",
996+
"pgp",
997+
"token",
998+
"x509",
999+
"jwk",
1000+
"all-keys",
1001+
"full"
1002+
],
1003+
"minimal_example_commands": [
1004+
{
1005+
"name": "RSA + JWK",
1006+
"command": "cargo run -p uselesskey --example basic_rsa --no-default-features --features rsa,jwk",
1007+
"description": "Generate RSA fixtures and JWK output."
1008+
},
1009+
{
1010+
"name": "Token fixtures",
1011+
"command": "cargo run -p uselesskey --example token_generation --no-default-features --features token",
1012+
"description": "Emit API key and bearer/OAuth token shapes."
1013+
},
1014+
{
1015+
"name": "X.509 + rustls",
1016+
"command": "cargo run -p uselesskey --example adapter_rustls --no-default-features --features x509",
1017+
"description": "Build rustls configs from generated cert fixtures."
1018+
}
1019+
],
1020+
"sync_targets": [
1021+
{
1022+
"path": "README.md",
1023+
"blocks": [
1024+
"dependency-snippets",
1025+
"runnable-examples",
1026+
"workspace-crates",
1027+
"adapter-crates",
1028+
"feature-matrix-facade",
1029+
"feature-matrix-adapters"
1030+
]
1031+
},
1032+
{
1033+
"path": "crates/uselesskey/README.md",
1034+
"blocks": [
1035+
"dependency-snippets"
1036+
]
1037+
},
1038+
{
1039+
"path": "docs/how-to/choose-features.md",
1040+
"blocks": [
1041+
"dependency-snippets",
1042+
"minimal-example-commands"
1043+
]
8951044
}
8961045
]
8971046
}

0 commit comments

Comments
 (0)