docs: restructure documentation #13162
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
📝 WalkthroughWalkthroughMassive documentation overhaul: reorganized site navigation, added Helm install guides and platform prerequisites, externalized many inline script samples into includes/placeholders, fixed image and script links (cedarling and auth-server), added navigation stylesheet, and removed numerous placeholder "in progress" docs. No application code changes. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
mo-auto
added
area-documentation
Member
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 30
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (9)
docs/script-catalog/id_generator/id-generator.md (1)
58-90:⚠️ Potential issue | 🟠 MajorFix Java sample class/interface and
Maptype syntax.This is the ID Generator doc, but the sample declares
EndSession/EndSessionType, and theMap<String SimpleCustomProperty>type is invalid Java syntax. This makes the sample misleading and non-compilable.✅ Proposed fix (align names + fix type)
-public class EndSession implements EndSessionType { +public class IdGenerator implements IdGeneratorType { @@ - public String generateId(String appId, String idType, String idPrefix, Map<String SimpleCustomProperty> configurationAttributes) { + public String generateId(String appId, String idType, String idPrefix, + Map<String, SimpleCustomProperty> configurationAttributes) {docs/script-catalog/client_registration/client-registration.md (1)
64-200: 🧹 Nitpick | 🔵 TrivialConsider externalizing the Java sample for consistency.
The Python sample has been externalized to an external file (line 65), but the Java sample remains inline (lines 70-200). For consistency with the PR objective of establishing "a single source of truth" and to maintain uniform documentation patterns across all script catalog entries, consider externalizing the Java sample as well.
♻️ Suggested approach to externalize the Java sample
Replace the inline Java code (lines 70-200) with:
### Script Type: Java ```java --- -import io.jans.as.common.model.registration.Client; -import io.jans.as.persistence.model.Scope; -import io.jans.as.server.service.ScopeService; -... -(remaining inline code) -``` +--8<-- "script-catalog/client_registration/sample-script/SampleScript.java"Then create the external file at `docs/script-catalog/client_registration/sample-script/SampleScript.java` with the Java code. </details> </blockquote></details> <details> <summary>docs/script-catalog/health_check/health-check.md (2)</summary><blockquote> `8-8`: _⚠️ Potential issue_ | _🟡 Minor_ **Incorrect heading for Health Check documentation.** The heading "Create User Custom Script" does not match the document content, which describes the "HealthCheck" custom script. <details> <summary>📝 Proposed fix</summary> ```diff -# Create User Custom Script +# Health Check Custom Script
37-95:⚠️ Potential issue | 🟠 MajorRemove duplicate inline code sample.
The inline Java code (lines 37-95) duplicates the external file reference added at lines 101-103. Per the PR objectives to "establish a single source of truth" by embedding external code files, the inline code should be removed to avoid maintenance burden and inconsistencies.
Additionally, line 37 contains typos: "Saample Scrip" should be "Sample Script".
♻️ Proposed fix: Remove the duplicate inline section
- -### Saample Scrip in Java - -```java -package io.jans.as.server._scripts; - -import io.jans.as.server.service.external.context.ExternalScriptContext; -import io.jans.model.SimpleCustomProperty; -import io.jans.model.custom.script.model.CustomScript; -import io.jans.model.custom.script.type.health.HealthCheckType; -import io.jans.service.custom.script.CustomScriptManager; -import jakarta.servlet.http.HttpServletRequest; -import org.slf4j.Logger; -import org.slf4j.LoggerFactory; - -import java.util.Map; - -/** - * `@author` Yuriy Z - */ -public class HealthCheck implements HealthCheckType { - - private static final Logger log = LoggerFactory.getLogger(HealthCheck.class); - private static final Logger scriptLogger = LoggerFactory.getLogger(CustomScriptManager.class); - - `@Override` - public String healthCheck(Object context) { - ExternalScriptContext scriptContext = (ExternalScriptContext) context; - HttpServletRequest httpRequest = scriptContext.getExecutionContext().getHttpRequest(); - - String appStatus = "running"; - String dbStatus = "online"; - return String.format("{\"status\": \"%s\", \"db_status\":\"%s\"}", appStatus, dbStatus); - } - - `@Override` - public boolean init(Map<String, SimpleCustomProperty> configurationAttributes) { - scriptLogger.info("Initialized HealthCheck Java custom script."); - return true; - } - - `@Override` - public boolean init(CustomScript customScript, Map<String, SimpleCustomProperty> configurationAttributes) { - scriptLogger.info("Initialized HealthCheck Java custom script."); - return true; - } - - `@Override` - public boolean destroy(Map<String, SimpleCustomProperty> configurationAttributes) { - scriptLogger.info("Destroyed HealthCheck Java custom script."); - return true; - } - - `@Override` - public int getApiVersion() { - return 11; - } -} - -```The external file reference at lines 97-103 provides the same code sample without duplication.
docs/script-catalog/idp/idp-extension.md (1)
22-23:⚠️ Potential issue | 🟡 MinorFix malformed markdown links in the method description table.
The URLs in lines 22-23 are malformed due to incorrect backtick placement. The current syntax prevents the links from being clickable.
🔗 Proposed fix for the link formatting
-| `def translateAttributes(self, context, configurationAttributes)` | context is `io.jans.idp.externalauth.TranslateAttributesContext` `(https://github.com/JanssenFederation/shib-oxauth-authn3/blob/master/src/main/java/io.jans.idp/externalauth/TranslateAttributesContext.java)`. configurationAttributes is `java.util.Map<String, SimpleCustomProperty>` | -| `def updateAttributes(self, context, configurationAttributes)` | context is `io.jans.idp.externalauth.TranslateAttributesContext` `(https://github.com/JanssenFederation/shib-oxauth-authn3/blob/master/src/main/java/io.jans.idp/externalauth/TranslateAttributesContext.java)`. configurationAttributes is `java.util.Map<String, SimpleCustomProperty>` | +| `def translateAttributes(self, context, configurationAttributes)` | context is [`io.jans.idp.externalauth.TranslateAttributesContext`](https://github.com/JanssenFederation/shib-oxauth-authn3/blob/master/src/main/java/io.jans.idp/externalauth/TranslateAttributesContext.java). configurationAttributes is `java.util.Map<String, SimpleCustomProperty>` | +| `def updateAttributes(self, context, configurationAttributes)` | context is [`io.jans.idp.externalauth.TranslateAttributesContext`](https://github.com/JanssenFederation/shib-oxauth-authn3/blob/master/src/main/java/io.jans.idp/externalauth/TranslateAttributesContext.java). configurationAttributes is `java.util.Map<String, SimpleCustomProperty>` |docs/script-catalog/select_account/select-account.md (1)
53-112: 🧹 Nitpick | 🔵 TrivialConsider externalizing the Java example for consistency.
The Python example has been externalized to an external file (line 54), but the Java example (lines 59-112) remains inline. This creates an inconsistency in how code samples are maintained and violates the "single source of truth" principle mentioned in the PR objectives.
Consider externalizing the Java example to a separate file (e.g.,
script-catalog/select_account/select-account/SelectAccount.java) and referencing it using the same snippets approach as Python.♻️ Proposed refactor to externalize Java example
### Script Type: Java ```java - -import io.jans.model.SimpleCustomProperty; -import io.jans.model.custom.script.model.CustomScript; - -import java.util.Map; - -/** - * `@author` Yuriy Z - */ -public class DummySelectAccountType implements SelectAccountType { - - `@Override` - public String getSelectAccountPage(Object context) { - return ""; - } - - `@Override` - public boolean prepare(Object context) { - return true; - } - - `@Override` - public String getAccountDisplayName(Object context) { - return ""; - } - - `@Override` - public boolean onSelect(Object context) { - return false; - } - - `@Override` - public boolean init(Map<String, SimpleCustomProperty> configurationAttributes) { - return true; - } - - `@Override` - public boolean init(CustomScript customScript, Map<String, SimpleCustomProperty> configurationAttributes) { - return true; - } - - `@Override` - public boolean destroy(Map<String, SimpleCustomProperty> configurationAttributes) { - return true; - } - - `@Override` - public int getApiVersion() { - return 1; - } -} - +--8<-- "script-catalog/select_account/select-account/SelectAccount.java"</details> </blockquote></details> <details> <summary>docs/script-catalog/dynamic_scope/dynamic-scope.md (2)</summary><blockquote> `73-84`: _🧹 Nitpick_ | _🔵 Trivial_ **Consider clarifying the dual init method overloads.** The Java sample includes two `init` method overloads—one with just `configurationAttributes` and another with both `customScript` and `configurationAttributes`. While line 20 mentions including `customScript` when `getApiVersion` > 10, the Java sample section doesn't explain which overload to use or why both exist. This could confuse developers implementing the interface. <details> <summary>📝 Suggested clarification</summary> Consider adding a brief comment above the overloaded methods explaining the API versioning: ```diff + // Legacy init method for API version <= 10 `@Override` public boolean init(Map<String, SimpleCustomProperty> configurationAttributes) { log.info("Dynamic Scope. Initializing..."); log.info("Dynamic Scope. Initialized"); return true; } + // New init method for API version > 10 (includes CustomScript parameter) `@Override` public boolean init(CustomScript customScript, Map<String, SimpleCustomProperty> configurationAttributes) { log.info("Dynamic Scope. Initializing..."); log.info("Dynamic Scope. Initialized"); return true; }
127-131:⚠️ Potential issue | 🔴 CriticalFix broken relative paths to sample script references.
The relative paths use
../../../script-catalog/dynamic_scope/which resolves to the repository root and fails to locate the referenced directories. The sample script directories (dynamic-permission, memberof-attribute, org-name, session-parameter, work-phone) exist in the same directory as this file. Update the links to use relative paths like./dynamic-permissionor simplydynamic-permission.docs/script-catalog/revoke_token/revoke-token.md (1)
58-88:⚠️ Potential issue | 🟡 MinorFix inconsistent Java code indentation.
The Java code example has inconsistent indentation that would cause compilation issues if users copy-paste it. Methods at lines 59-82 have body content indented with 8 spaces while the class structure uses 4 spaces.
📝 Proposed fix for consistent indentation
`@Override` - public boolean init(Map<String, SimpleCustomProperty> configurationAttributes) { + public boolean init(Map<String, SimpleCustomProperty> configurationAttributes) { log.info("Token Revoke. Initializing..."); log.info("Token Revoke. Initialized"); return true; - } + } - `@Override` - public boolean init(CustomScript customScript, Map<String, SimpleCustomProperty> configurationAttributes) { + `@Override` + public boolean init(CustomScript customScript, Map<String, SimpleCustomProperty> configurationAttributes) { log.info("Token Revoke. Initializing..."); log.info("Token Revoke. Initialized"); return true; - } + } - `@Override` - public boolean destroy(Map<String, SimpleCustomProperty> configurationAttributes) { + `@Override` + public boolean destroy(Map<String, SimpleCustomProperty> configurationAttributes) { log.info("Token Revoke. Destroying..."); log.info("Token Revoke. Destroyed."); return true; - } + } - `@Override` - public int getApiVersion() { - return 11; - } + `@Override` + public int getApiVersion() { + return 11; + }
🤖 Fix all issues with AI agents
In `@docs/cedarling/developer/sidecar/cedarling-sidecar-overview.md`:
- Line 93: Add a trailing period to the end of the sentence in
cedarling-sidecar-overview.md that reads "A more detailed example of creating an
AuthZen request can be seen in the [gateway
example](./cedarling-sidecar-tutorial.md#setup-test-gateway)"; update that line
so it ends with a period for consistency and readability.
In `@docs/cedarling/reference/cedarling-authz.md`:
- Line 24: The markdown image currently has no alt text
(""); update that line to include
descriptive alt text that conveys the image content (for example: "") so MD045 passes and the document
is accessible; ensure the alt string succinctly describes the diagram's purpose
and key elements.
In `@docs/cedarling/reference/cedarling-jwt-validation.md`:
- Line 177: The image markdown line uses an empty alt field
(""); update it to include
descriptive alt text (e.g., "") so the file
cedarling-jwt-validation.md satisfies accessibility/MD045 and explains the
diagram for screen readers.
In `@docs/janssen-server/auth-server/openid-features/prompt-parameter.md`:
- Around line 28-29: Change the grammatically incorrect phrase "If more or
custom fields has to be shown" to "If more or custom fields have to be shown" in
the sentence that references the "CreateUser" custom script redirect; ensure
only the verb "has" is replaced with "have" so the sentence reads correctly
while keeping the rest of the wording (including the reference to the
"CreateUser" custom script) unchanged.
In `@docs/janssen-server/install/helm-install/database-setup.md`:
- Around line 31-34: The wget URLs in the database-setup docs use the incorrect
placeholder "vreplace-janssen-version" which the CI sed step won't replace;
update the wget lines (the URLs that fetch raw.githubusercontent.com in this
file, e.g., the commands shown calling wget for pgsql.yaml) to use
"replace-janssen-version" instead of "vreplace-janssen-version" (and make the
same change in the other affected block around lines 58–61), or alternatively
update the build workflow to perform substitutions for both
"replace-janssen-version" and "vreplace-janssen-version".
In `@docs/janssen-server/install/helm-install/ingress-setup.md`:
- Around line 72-83: Add a clear retirement notice above the "Install Nginx
Ingress Controller" section (under the "Option 2: Kubernetes Ingress (Legacy)"
heading) stating that the upstream ingress-nginx project
(kubernetes/ingress-nginx) is in a terminal maintenance window through March
2026 and will receive no further releases, bug fixes, or security updates after
that date; keep the existing helm install instructions but prepend a short
advisory recommending alternative maintained controllers or a migration plan and
link to the upstream retirement announcement for reference.
In `@docs/janssen-server/install/helm-install/install-janssen.md`:
- Around line 48-52: The Helm install uses namespace "jans" but doesn't ensure
it exists; either add the --create-namespace flag to the helm install command
(the line with "helm install janssen janssen/janssen -n jans -f override.yaml")
or prepend an explicit namespace creation step that runs "kubectl create
namespace jans --dry-run=client -o yaml | kubectl apply -f -" before calling
helm; update the docs accordingly so the install will not fail when the "jans"
namespace is missing.
- Around line 16-37: The example YAML exposes plaintext DB credentials
(cnSqlDbUser and cnSqldbUserPassword) — update the example under the
config.configmap block to add inline comments next to cnSqlDbUser and
cnSqldbUserPassword (e.g., "Use a dedicated user in production" and "Change for
production!") and append a short admonition/warning block after the YAML (e.g.,
!!! warning "Security" Replace example credentials with secure values for
production deployments.) so readers are clearly warned if they copy the snippet.
In `@docs/janssen-server/install/helm-install/post-install.md`:
- Around line 21-23: Remove the trailing whitespace at the end of the "Expected
output shows pods in `Running` or `Completed` state." line (and any trailing
spaces on the blank line before the "## Configure Janssen with TUI" header) so
the markdown satisfies MD009; open the file, trim end-of-line spaces for that
sentence and the following blank line, and save the file.
In `@docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md`:
- Around line 27-31: Add blank lines immediately before the opening fenced code
block and immediately after the closing fence that contains the eksctl create
cluster command (the ```bash block with "eksctl create cluster --name
janssen-cluster ..."); ensure there is an empty line above the "```bash" line
and an empty line below the closing "```" to satisfy markdownlint rule MD031.
- Around line 18-20: Update the phrase "service linked roles" to the hyphenated
compound modifier "service-linked roles" in the sentence that lists required AWS
permissions (the line containing "service linked roles, AWS CloudFormation, and
VPC resources") so the documentation reads correctly as "service-linked roles."
In `@docs/janssen-server/install/helm-install/prerequisites/google-gke.md`:
- Around line 23-26: The fenced code block containing "gcloud components install
kubectl" is missing surrounding blank lines (MD031); edit the markdown in
google-gke.md to insert one blank line before the triple-backtick fence and one
blank line after the closing triple-backtick so the code block is separated from
adjacent text and satisfies MD031.
In `@docs/janssen-server/install/helm-install/prerequisites/local.md`:
- Around line 43-46: The download URL uses the placeholder branch
"vreplace-janssen-version" which will 404; update the URL in the
startjanssendemo.sh download line to reference a real release tag or a
documented MkDocs variable (e.g. use a template variable like {{ jans_version }}
that the build injects) so the wget points to an existing release, and ensure
the surrounding text documents how to set that variable; locate the line
invoking wget for startjanssendemo.sh and replace the placeholder segment
"vreplace-janssen-version" accordingly.
In `@docs/janssen-server/install/helm-install/prerequisites/rancher.md`:
- Around line 25-27: Replace the unstable image tag in the docker run command
that currently uses rancher/rancher:latest with a specific, pinned release
(e.g., rancher/rancher:v2.13.2) to ensure reproducible deployments; update the
example command string where the docker run invocation is shown so it references
the pinned tag instead of :latest and consider adding a short note recommending
using a fixed version for production.
In `@docs/janssen-server/install/helm-install/README.md`:
- Around line 14-31: The fenced ASCII-art code block in README.md lacks a
language specifier; update the opening triple-backtick to include a plain text
specifier (e.g., change "```" to "```text" or "```plaintext") so the
installation flow diagram renders consistently; ensure the closing
triple-backtick remains unchanged.
In `@docs/script-catalog/ciba/ciba.md`:
- Around line 100-106: The End User Notification Script is duplicated: the
document currently includes a full inline Python block earlier and again uses an
include for "script-catalog/ciba/end-user-notification/end_user_notification.py"
under the "End User Notification Script" heading; pick one source of truth by
either replacing the earlier inline block with this include or removing this
include and keeping the inline code, and update the "End User Notification
Script" section to reference only the chosen source (the include path
"script-catalog/ciba/end-user-notification/end_user_notification.py" or the
earlier inline snippet) so the content appears only once.
In `@docs/script-catalog/client_authn/client-authn.md`:
- Around line 146-152: There are duplicate Java samples for the client authn
script — the full inline Java sample and the snippet include referencing
ClientAuthn.java; remove the earlier full inline Java block and replace it with
the snippet include form (--8<-- "script-catalog/client_authn/ClientAuthn.java")
so only the canonical sample remains under the "Client Authentication Script"
section, ensuring any references to ClientAuthn.java or the inline block are
updated/removed to avoid two sources of truth.
In `@docs/script-catalog/create_user/create-user.md`:
- Around line 244-250: The docs contain a duplicated Java sample for the Create
User script; remove the duplicate by keeping a single source of truth—either
replace the earlier inline Java sample with the include reference to
"script-catalog/create_user/CreateUser.java" or delete this include block here
so only the earlier inline sample remains. Update the markdown around the Create
User example so only one reference to CreateUser.java (the "CreateUser.java"
snippet include) exists and ensure links/anchors still point to that single
sample.
In `@docs/script-catalog/dynamic_scope/dynamic-scope.md`:
- Line 71: Remove the trailing whitespace on the blank line in the "Dynamic
Scope" section of the markdown: open the dynamic-scope.md file, locate the blank
line after the section content (the line with invisible trailing spaces), and
delete the extra spaces so the line ends cleanly (no trailing tabs or spaces).
Ensure the file uses normal line endings and save.
In `@docs/script-catalog/fido2_extension/fido2-extension.md`:
- Line 58: The mkdocs.yml is missing the pymdownx.snippets extension needed to
process the include directive used in the docs; open mkdocs.yml and add
"pymdownx.snippets" to the markdown_extensions list (alongside any existing
pymdownx or other markdown extensions) so the include directive --8<--
"script-catalog/fido2_extension/Fido2ExtensionSample.py" is processed; also
ensure the project environment has the pymdown-extensions package installed so
the extension is available at build time.
In `@docs/script-catalog/person_authentication/person-authentication.md`:
- Around line 376-401: Update the documentation text to use “third‑party”
consistently instead of “third party” and change the phrase “return the control
back” to “return control”; search for occurrences in the person authentication
script section (including prose and code comments around getPageForStep,
redirect.xhtml, prepareForStep, and the postlogin.htm example) and replace each
instance to use the hyphenated “third‑party” and the concise “return control”
wording to keep terminology consistent and concise.
In `@docs/script-catalog/post_authn/post-authentication.md`:
- Line 64: The logger declaration references the wrong class: replace the
copy-pasted CustomScriptManager.class used in the LoggerFactory.getLogger(...)
call with the current class PostAuthn (i.e., initialize the Logger for PostAuthn
instead of CustomScriptManager) so the logger variable in class PostAuthn
correctly reflects its owning class.
In `@docs/script-catalog/resource_owner_password_credentials/ropc.md`:
- Around line 108-112: The string comparison for device_id uses reference
equality (deviceIdParam[0] == "device_id_1") which is incorrect; update the
boolean assignment in that block (the line assigning result) to use content
equality, e.g. use "device_id_1".equals(deviceIdParam[0]) or
deviceIdParam[0].equals("device_id_1") with a null-safe check, so that the
comparison in the method that contains deviceIdParam is correct and won’t throw
NPEs.
- Around line 108-116: The branch that handles deviceIdParam returns true
without setting the authenticated user on the context; update the block that
checks deviceIdParam (using deviceIdParam, result) to call
ropcContext.setUser(user) with the appropriate User/Principal before returning
true so the flow is authenticated; ensure you use the same user variable that
other branches set (or construct it similarly) and then return true.
In `@docs/script-catalog/scim/scim.md`:
- Around line 319-321: The fenced code block using the include marker (--8<--
"script-catalog/scim/sample-script/custom_scim_handler.py") violates MD046;
update the block style to match the repository's configured markdown style
(either change to the alternative fenced style or convert to
indented/code-include format) where this appears (the include lines referencing
"script-catalog/scim/sample-script/custom_scim_handler.py" at the reported
locations and the similar block around lines 334-336), ensuring the syntax
matches the project's MD046 configuration so the linter no longer flags these
blocks.
In `@docs/script-catalog/tx_token/txtoken.md`:
- Around line 41-43: The mkdocs build won't expand the snippet marker `--8<--
"script-catalog/tx_token/TxToken.java"` because the pymdownx.snippets extension
is missing; open mkdocs.yml and add the pymdownx.snippets extension and
configure its base_path to include the docs root (so the path
`script-catalog/tx_token/TxToken.java` is resolvable), ensuring the extension is
listed under markdown_extensions and base_path points to the directory
containing the `script-catalog` folder.
In `@docs/script-catalog/uma_claims_gathering/uma-claims-web.md`:
- Around line 39-41: The snippet include using the --8<--
"script-catalog/uma_claims_gathering/uma-claims-gathering/uma_claims_gathering.py"
syntax requires the pymdownx.snippets extension; open mkdocs.yml and add
"pymdownx.snippets" to the markdown_extensions list (and ensure the
pymdown-extensions package is installed in your environment) so the snippet
include will render correctly.
In `@docs/script-catalog/uma_rpt_policy/uma-rpt.md`:
- Around line 109-118: The authorize method may call getClaim(...) and then
.equals(...) which can NPE if a claim is missing; update authorize (method name:
authorize in the UMA RPT Policy) to perform null-safe comparisons by either
retrieving claims into local variables and checking for null (e.g., String
country = authContext.getClaim("country"); if (country != null &&
country.equals("US") ...), or by using constant-first equals (e.g.,
"US".equals(authContext.getClaim("country")) and
"NY".equals(authContext.getClaim("city"))); ensure UmaAuthorizationContext
authContext is still cast as shown and keep the same success logging and return
behavior.
- Around line 65-66: The logger declaration uses CustomScriptManager.class
causing logs to be attributed incorrectly; update the Logger initialization (the
private static final Logger log field) to use UmaRptPolicy.class instead of
CustomScriptManager.class so that log messages are emitted under the
UmaRptPolicy class identity.
- Around line 94-107: The json variable in getRequiredClaims is left empty so no
claims are returned; replace it with a clear TODO/example JSON string (or pull
from configuration) containing a valid JSON array of claim definitions (using
authContext.getIssuer() where needed) and document that users must customize it;
update the method UmaAuthorizationContext usage and the call to
ClaimDefinitionBuilder.build to use that populated JSON string (or load it from
external config) and add a one-line TODO comment above json to make
customization explicit.
docs/janssen-server/auth-server/openid-features/prompt-parameter.md
Outdated
Show resolved
Hide resolved
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
docs/script-catalog/post_authn/post-authentication.md (2)
57-57:⚠️ Potential issue | 🟡 MinorRemove unused import.
The
CustomScriptManagerimport is no longer used in the code after the logger was corrected to referencePostAuthn.classon line 64.🧹 Proposed fix
import io.jans.model.custom.script.model.CustomScript; import io.jans.model.custom.script.type.postauthn.PostAuthnType; -import io.jans.service.custom.script.CustomScriptManager; import org.slf4j.Logger;
52-102: 🧹 Nitpick | 🔵 TrivialConsider externalizing Java code for consistency.
The Python example was externalized to a separate file (line 46), but the Java example remains inline. For consistency and to maintain a single source of truth for both language examples, consider externalizing the Java code as well.
If there's an external Java file available, you could replace this inline code with:
-```java -import java.util.Map; -... -} - -``` +```java +--8<-- "script-catalog/post_authn/post-authn/PostAuthn.java" +```
🤖 Fix all issues with AI agents
In `@docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md`:
- Line 23: The line containing the eksctl link
("https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html")
has a trailing space after the closing parenthesis; remove that trailing space
so the line reads "Install
[eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html)"
without any extra whitespace to maintain consistency and clean Markdown
formatting.
In `@docs/janssen-server/install/helm-install/prerequisites/rancher.md`:
- Line 26: Update the pinned Rancher image tag used in the Docker run example:
replace the existing image reference "rancher/rancher:v2.10.2" with the newer
stable release "rancher/rancher:v2.13.2" in the line that currently reads the
docker run command so users pull the latest stable build while still pinning a
specific version.
In `@docs/script-catalog/post_authn/post-authentication.md`:
- Line 46: Remove the unused import of CustomScriptManager from the Java
snippet: locate the import statement referencing CustomScriptManager (the unused
symbol) and delete that import line, and then verify there are no remaining
references to CustomScriptManager in the snippet (remove any accidental leftover
usage if present).
In `@docs/script-catalog/update_token/update-token.md`:
- Around line 267-268: Rewrite the "Core Purpose" table row so the second cell
is a complete, grammatically correct sentence and replace "a criteria" with "a
criterion"; specifically edit the table entry under "Core Purpose" (the cell
describing introspection and token transformations) to read as a full sentence
that clearly states the purposes (e.g., that the introspection endpoint returns
token meta information and that the script can enable claim transformation, set
token lifetimes, change access granularity, perform audit logging, and forbid AT
creation based on a criterion), and ensure the reference to UpdateToken remains
intact.
docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md
Outdated
Show resolved
Hide resolved
docs/janssen-server/install/helm-install/prerequisites/rancher.md
Outdated
Show resolved
Hide resolved
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 7
🤖 Fix all issues with AI agents
In @.github/workflows/build-docs.yml:
- Around line 78-80: The "Sync CHANGELOG to docs" step currently runs before the
second checkout and will be overwritten for workflow_dispatch runs; either move
the "Sync CHANGELOG to docs" step so it executes after the version checkout
(i.e., after the second checkout block) or add a copy of CHANGELOG.md into the
"Copy files from main" step so the docs/CHANGELOG.md is restored after the
second checkout; update the workflow accordingly and ensure the step names
("Sync CHANGELOG to docs" and "Copy files from main") are used to locate and
modify the correct steps.
In `@docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md`:
- Around line 35-37: Add a one-sentence note before the EBS CSI driver link
under the "## Install the EBS CSI Driver" heading that the driver requires an
IAM role/policy for node or service account access (e.g., mention "requires
creating an IAM role or ServiceAccount with appropriate permissions for EBS
CSI"), and optionally point readers to the AWS IAM setup docs or the linked CSI
IAM-role guide for details; keep it concise and placed immediately before the
existing link to make the prerequisite clear.
- Around line 29-33: The eksctl command shown uses placeholders NODE_TYPE and
REGION_CODE without examples; update the documentation around the command (the
block containing "eksctl create cluster --name janssen-cluster --nodegroup-name
jans-nodes --node-type NODE_TYPE --nodes 2 --managed --region REGION_CODE") to
add a brief note explaining what to replace them with — e.g., "Replace NODE_TYPE
with an instance type (for example: t3.xlarge, m5.large) and REGION_CODE with
your AWS region (for example: us-east-1, eu-west-1)." Keep the note immediately
adjacent to the command so users know which values to use.
In `@docs/janssen-server/install/helm-install/prerequisites/rancher.md`:
- Line 61: Add a short explanatory sentence after Step 3 clarifying that "Wait"
should be unselected because leaving it selected makes Helm wait for all
resources to reach a ready state (which can cause the install to hang or time
out in UI-driven installs), whereas unselecting it allows the release to be
created asynchronously and the UI to return immediately; also note the trade-off
that you’ll need to check resource readiness separately if you unselect "Wait".
- Around line 15-19: The VM spec list (the 4 CPU / 16 GB / 50 GB / ports 443 &
80 items) should be annotated to indicate these are minimum recommended specs
for testing/demo/single-node Rancher installs, not production; update the text
around that list to add a short sentence like "These are minimum specs for
testing or single-node/demo installations — production environments require
higher resources and HA configurations (see Rancher production requirements),"
and optionally add a link or pointer to the Rancher production sizing/HA
documentation for operators.
- Around line 37-41: Update the wording that currently says "The final line of
the docker run output is the container-id" to clarify that "docker run -d"
outputs only the container ID (so capture that single-line output) and that
users may alternatively obtain the container ID later via "docker ps" before
running the provided "docker logs <container-id> 2>&1 | grep 'Bootstrap
Password:'" command; reference the docker run -d invocation and the docker ps
and docker logs commands so readers know exactly how to retrieve the container
ID.
- Around line 23-33: Add a clear production warning to the "Start Rancher"
section (the block containing the docker run snippet) stating that single-node
Docker installations are not supported for production and are intended only for
testing/development; instruct users to use a high-availability, Kubernetes-based
Helm installation for production and link to Rancher's official HA/Helm
installation docs for guidance. Ensure the warning is prominent (e.g., an
admonition/note) immediately above or below the docker run example and keep the
existing "Version Pinning" tip and port/ingress note intact.
docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md
Outdated
Show resolved
Hide resolved
docs/janssen-server/install/helm-install/prerequisites/amazon-eks.md
Outdated
Show resolved
Hide resolved
docs/janssen-server/install/helm-install/prerequisites/rancher.md
Outdated
Show resolved
Hide resolved
docs/janssen-server/install/helm-install/prerequisites/rancher.md
Outdated
Show resolved
Hide resolved
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 0
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
.github/workflows/build-docs.yml (1)
87-93:⚠️ Potential issue | 🟠 MajorPreserve CHANGELOG before the version checkout for workflow_dispatch.
Line 92 copies
../CHANGELOG.md, but that file is never created before the second checkout, soworkflow_dispatchruns will fail here. Save the changelog from main before the version checkout (or source it viagit show) so the copy step has a valid file.🔧 Proposed fix
- name: Install dependencies run: | curl -sSL https://install.python-poetry.org | python3 - export PATH="$HOME/.local/bin:$PATH" cp docs/pyproject.toml docs/poetry.lock ../ poetry install --no-root cp mkdocs.yml ../ + + - name: Preserve CHANGELOG from main + if: github.event_name == 'workflow_dispatch' + run: | + cp CHANGELOG.md ../CHANGELOG.md
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@mkdocs.yml`:
- Around line 43-47: Remove the unnecessary root path from the pymdownx.snippets
configuration: edit the pymdownx.snippets block and set base_path to only
include "docs" (remove the "." entry) so that base_path lists just docs and keep
check_paths: true; update the stanza that defines pymdownx.snippets and its
base_path to drop the "." entry to restrict snippet resolution to the docs
directory.
Signed-off-by: moabu <47318409+moabu@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@mkdocs.yml`:
- Around line 364-368: The nav in mkdocs.yml contains duplicate entries for the
same pages (casa/administration/faq.md, janssen-server/developer/agama/faq.md,
janssen-server/planning/components.md) under different labels; decide whether
duplicates are intentional and either remove the redundant nav entries or add an
inline YAML comment next to each duplicated nav item documenting why the page
appears twice for discoverability (e.g., “# intentional duplicate for X”), then
consolidate or update labels to a single canonical entry if unintentional so the
navigation only references each unique page once.
Comment on lines
+364
to
+368
| - FAQ & Troubleshooting: | ||
| - Install FAQ: janssen-server/install/install-faq.md | ||
| - Developer FAQ: contribute/developer-faq.md | ||
| - Casa FAQ: casa/administration/faq.md | ||
| - Agama FAQ: janssen-server/developer/agama/faq.md |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Intentional duplicates? Verify navigation cross-references.
Several pages appear multiple times in the navigation with different labels:
| Page | First Location | Second Location |
|---|---|---|
casa/administration/faq.md |
Line 307 (Casa > FAQ) | Line 367 (Test & Debug > Casa FAQ) |
janssen-server/developer/agama/faq.md |
Line 144 (Agama > FAQ) | Line 368 (Test & Debug > Agama FAQ) |
janssen-server/planning/components.md |
Line 376 (Planning > Components) | Line 472 (Architecture > Components Overview) |
If intentional for discoverability, consider adding a comment in the YAML to document this pattern for future maintainers. If unintentional, consolidating would reduce maintenance overhead.
🤖 Prompt for AI Agents
In `@mkdocs.yml` around lines 364 - 368, The nav in mkdocs.yml contains duplicate
entries for the same pages (casa/administration/faq.md,
janssen-server/developer/agama/faq.md, janssen-server/planning/components.md)
under different labels; decide whether duplicates are intentional and either
remove the redundant nav entries or add an inline YAML comment next to each
duplicated nav item documenting why the page appears twice for discoverability
(e.g., “# intentional duplicate for X”), then consolidate or update labels to a
single canonical entry if unintentional so the navigation only references each
unique page once.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Enhanced the visual appearance with MkDocs Material features:
Reorganized mkdocs.yml navigation from ~265 items in 6 sections to ~93 items in 7 user-friendly sections:
Before: 5 files with 80% content overlap
After: 10 focused files:
Added pymdownx.snippets extension to embed code files directly:
Closes fix: docs: restructure documentation -autocreated #13163,
Summary by CodeRabbit