libre.sh/keycloak-scim
3
0
Fork 0
Code Issues 15 Pull requests Releases 1 Packages Activity Actions

KEYCLOAK-11918 Add latest and archive builds to documentation

Browse source
This commit is contained in:
stianst 2019-11-06 10:57:00 +01:00 committed by Stian Thorgersen
parent 2dd592380d
commit 384640c284
17 changed files with 137 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

@ -35,6 +35,10 @@ To build Keycloak Documentation run:
Or to build a specific guide run:
mvn clean install -f GUIDE_DIR
By default an archive version of the documentation is built. To build a latest build run:
mvn clean install -Dlatest
You can then view the documentation by opening GUIDE_DIR/target/generated-docs/index.html.

38
aggregation/navbar-head.html
View file

@ -13,6 +13,44 @@
#tocbot a.toc-link.node-name--H4{ display:none }
}
.versionarchive {
display: inline-block;
}
.versionarchive p {
background-color: #eee;
border-radius: 5px;
margin: 0;
padding: 2px 5px 2px 10px;
}
.versionarchive a {
background-color: #ffdd57;
padding: 0 5px;
font-style: normal;
border-radius: 5px;
margin-left: 10px;
}
.versionlatest {
display: inline-block;
}
.versionlatest p {
background-color: #eee;
border-radius: 5px;
margin: 0;
padding: 2px 5px 2px 10px;
}
.versionlatest em {
background-color: #23d160;
padding: 0 5px;
font-style: normal;
border-radius: 5px;
margin-left: 10px;
}
/* Fix scroll to anchor hides title */
h1::before, h2::before, h3::before, h4::before, h5::before, h6::before {
display: block;

3
authorization_services/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {authorizationguide_name}
:release_header_latest_link: {authorizationguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

3
getting_started/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {gettingstarted_name}
:release_header_latest_link: {gettingstarted_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

18
pom.xml
View file

@ -22,9 +22,10 @@
<version.jar.plugin>3.0.2</version.jar.plugin>
<version.install.plugin>2.5.2</version.install.plugin>
<maven.compiler.target>1.8</maven.compiler.target>
<maven.compiler.source>1.8</maven.compiler.source>
<buildType>archive</buildType>
</properties>
<modules>
@ -56,6 +57,17 @@
<imagesDir>rhsso-images</imagesDir>
</properties>
</profile>
<profile>
<id>latest</id>
<activation>
<property>
<name>latest</name>
</property>
</activation>
<properties>
<buildType>latest</buildType>
</properties>
</profile>
</profiles>
<build>
@ -93,7 +105,7 @@
</goals>
<configuration>
<target>
<echo>OUTPUT: file://${project.build.directory}/generated-docs/${masterFile}.html</echo>
<echo>OUTPUT: file://${project.build.directory}/generated-docs/${masterFile}.html ${projectLatestBuild}</echo>
</target>
</configuration>
</execution>
@ -117,7 +129,6 @@
<configuration>
<masterFile>${masterFile}</masterFile>
</configuration>
</execution>
</executions>
</plugin>
@ -148,6 +159,7 @@
<idseparator>-</idseparator>
<docinfo1>true</docinfo1>
<masterFile>${masterFile}</masterFile>
<project_buildType>${buildType}</project_buildType>
</attributes>
<resources>
<resource>

5
release_notes/index.adoc
View file

@ -9,6 +9,9 @@ include::topics/templates/document-attributes-community.adoc[]
= {releasenotes_name}
:release_header_latest_link: {releasenotes_link_latest}
include::topics/templates/release-header.adoc[]
== {project_name_full} 7.0.1.Final
include::topics/7_0_1_final.adoc[leveloffset=2]
@ -47,4 +50,4 @@ include::topics/4_1_0_final.adoc[leveloffset=2]
== {project_name_full} 4.0.0.Final
include::topics/4_0_0_final.adoc[leveloffset=2]
include::topics/4_0_0_beta3.adoc[leveloffset=2]
include::topics/4_0_0_beta3.adoc[leveloffset=2]

3
securing_apps/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {adapterguide_name}
:release_header_latest_link: {adapterguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

3
server_admin/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {adminguide_name}
:release_header_latest_link: {adminguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

3
server_development/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {developerguide_name}
:release_header_latest_link: {developerguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

3
server_installation/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {installguide_name}
:release_header_latest_link: {installguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]

2
server_installation/topics/operating-mode/crossdc.adoc
View file

@ -755,7 +755,7 @@ For the environments with slower network between data centers and probability of
* It is recommended to keep the `sessions` and `clientSessions` caches in `SYNC`. Switching them to `ASYNC` is possible only if you are sure that user requests and backchannel requests (requests from client applications to {project_name} as described in <<requestprocessing>>) will be always processed on same site. This is true, for example, if:
** You use active/passive mode as described <<modes>>.
** All your client applications are using the {project_name} link:https://www.keycloak.org/docs/latest/securing_apps/index.html#_javascript_adapter[JavaScript Adapter]. The JavaScript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
** All your client applications are using the {project_name} {adapterguide_link_js_adapter}[JavaScript Adapter]. The JavaScript adapter sends the backchannel requests within the browser and hence they participate on the browser sticky session and will end on same cluster node (hence on same site) as the other browser requests of this user.
** Your load balancer is able to serve the requests based on client IP address (location) and the client applications are deployed on both sites.
+
For example you have 2 sites LON and NYC. As long as your applications are deployed in both LON and NYC sites too, you can ensure that all the user requests from London users will be redirected to the applications in LON site and also to the {project_name} servers in LON site. Backchannel requests from the LON site client deployments will end on {project_name} servers in LON site too. On the other hand, for the American users, all the {project_name} requests, application requests and backchannel requests will be processed on NYC site.

6
tests/pom.xml
View file

@ -106,6 +106,12 @@
<version>1.2.17</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>2.1.0</version>
<scope>test</scope>
</dependency>
</dependencies>
<profiles>

38
tests/src/test/java/org/keycloak/documentation/test/Config.java
View file

@ -1,8 +1,11 @@
package org.keycloak.documentation.test;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOUtils;
import org.apache.log4j.Logger;
import org.asciidoctor.Asciidoctor;
import org.asciidoctor.AttributesBuilder;
import org.asciidoctor.OptionsBuilder;
import org.asciidoctor.ast.Document;
import java.io.File;
import java.io.IOException;
@ -50,7 +53,7 @@ public class Config {
}
documentAttributes = loadDocumentAttributes();
docBaseUrl = documentAttributes.get("project_doc_base_url").replace("{project_versionDoc}", documentAttributes.get("project_versionDoc"));
docBaseUrl = documentAttributes.get("project_doc_base_url");
guideBaseUrl = System.getProperty("guideBaseUrl");
if (guideBaseUrl != null) {
@ -62,7 +65,7 @@ public class Config {
if (isLoadFromFiles()) {
// Ignore api-docs link in unpublished docs
String apiDocsLink = documentAttributes.get("apidocs_link").replace("{project_doc_base_url}", docBaseUrl);
String apiDocsLink = documentAttributes.get("apidocs_link");
ignoredLinks.add(apiDocsLink);
}
@ -142,24 +145,21 @@ public class Config {
f = new File(docsRootDir, "/topics/templates/document-attributes-product.adoc");
}
String buildType = System.getProperty("latest") != null ? "latest" : "archive";
Asciidoctor asciidoctor = Asciidoctor.Factory.create();
Map<String, Object> options = OptionsBuilder.options()
.inPlace(true)
.attributes(AttributesBuilder.attributes().backend("html5").attribute("project_buildType", buildType).asMap())
.asMap();
Document document = asciidoctor.loadFile(f, options);
Map<String, String> attributes = new HashMap<>();
// Slight work around to CD block overriding attribute values
boolean useFirstAttribute = true;
for (String l : FileUtils.readLines(f, "utf-8")) {
if (l.startsWith(":")) {
String[] s = l.split(": ");
String key = s[0].substring(1).trim();
String value = s[1].trim();
if (!attributes.containsKey(key) || !useFirstAttribute) {
attributes.put(key, value);
}
if (key.equals("project_product_cd") && value.equals("true")) {
useFirstAttribute = false;
}
}
for (Map.Entry<String, Object> a : document.getAttributes().entrySet()) {
attributes.put(a.getKey(), a.getValue().toString());
}
return attributes;

22
topics/templates/document-attributes-community.adoc
View file

@ -6,8 +6,17 @@
:project_versionMvn: 8.0.0
:project_versionNpm: 8.0.0
:project_versionDoc: 8.0
ifeval::["{project_buildType}" == "latest"]
:project_versionLinks: latest
endif::[]
ifeval::["{project_buildType}" == "archive"]
:project_versionLinks: {project_versionDoc}
endif::[]
:project_images: keycloak-images
:project_doc_base_url: https://www.keycloak.org/docs/{project_versionDoc}
:project_doc_base_url: https://www.keycloak.org/docs/{project_versionLinks}
:project_doc_base_url_latest: https://www.keycloak.org/docs/latest
:project_dirref: KEYCLOAK_HOME
:project_openshift_product_name: Keycloak for OpenShift
@ -17,11 +26,15 @@
:authorizationguide_name: Authorization Services Guide
:authorizationguide_link: {project_doc_base_url}/authorization_services/
:authorizationguide_link_latest: {project_doc_base_url_latest}/authorization_services/
:adapterguide_name: Securing Applications and Services Guide
:adapterguide_link: {project_doc_base_url}/securing_apps/
:adapterguide_link_js_adapter: {adapterguide_link}#_javascript_adapter
:adapterguide_link_latest: {project_doc_base_url_latest}/securing_apps/
:adapterguide_logout_link: {adapterguide_link}#_java_adapter_logout
:adminguide_name: Server Administration Guide
:adminguide_link: {project_doc_base_url}/server_admin/
:adminguide_link_latest: {project_doc_base_url_latest}/server_admin/
:adminguide_bruteforce_name: Password guess: brute force attacks
:adminguide_bruteforce_link: {adminguide_link}#password-guess-brute-force-attacks
:adminguide_timeouts_name: Timeouts
@ -29,22 +42,27 @@
:adminguide_clearcache_name: Clearing Server Caches
:adminguide_clearcache_link: {adminguide_link}#_clear-cache
:apidocs_name: API Documentation
:apidocs_link: {project_doc_base_url}/api_documentation/
:apidocs_link: https://www.keycloak.org/docs/{project_versionDoc}/api_documentation/
:developerguide_name: Server Developer Guide
:developerguide_link: {project_doc_base_url}/server_development/
:developerguide_link_latest: {project_doc_base_url_latest}/server_development/
:developerguide_actiontoken_name: Action Token SPI
:developerguide_actiontoken_link: {developerguide_link}#_action_token_spi
:developerguide_jsproviders_name: JavaScript Providers
:developerguide_jsproviders_link: {developerguide_link}#_script_providers
:gettingstarted_name: Getting Started Guide
:gettingstarted_link: {project_doc_base_url}/getting_started/
:gettingstarted_link_latest: {project_doc_base_url_latest}/getting_started/
:upgradingguide_name: Upgrading Guide
:upgradingguide_link: {project_doc_base_url}/upgrading/
:upgradingguide_link_latest: {project_doc_base_url_latest}/upgrading/
:releasenotes_name: Release Notes
:releasenotes_link: {project_doc_base_url}/release_notes/
:releasenotes_link_latest: {project_doc_base_url_latest}/release_notes/
:installguide_name: Server Installation and Configuration Guide
:installguide_link: {project_doc_base_url}/server_installation/
:installguide_link_latest: {project_doc_base_url_latest}/server_installation/
:installguide_clustering_name: Clustering
:installguide_clustering_link: {installguide_link}#_clustering
:installguide_database_name: Database

1
topics/templates/document-attributes-product.adoc
View file

@ -38,6 +38,7 @@ endif::[]
:authorizationguide_link: {project_doc_base_url}/authorization_services_guide/
:adapterguide_name: Securing Applications and Services Guide
:adapterguide_link: {project_doc_base_url}/securing_applications_and_services_guide/
:adapterguide_link_js_adapter: {adapterguide_link}#_javascript_adapter
:adapterguide_logout_link: {adapterguide_link}#_java_adapter_logout
:adminguide_name: Server Administration Guide
:adminguide_link: {project_doc_base_url}/server_administration_guide/

8
topics/templates/release-header.adoc Normal file
View file

@ -0,0 +1,8 @@
ifeval::["{project_buildType}" == "latest"]
[.versionlatest]
Version *{project_version}* _Latest_
endif::[]
ifeval::["{project_buildType}" == "archive"]
[.versionarchive]
Version *{project_version}* _{release_header_latest_link}[Click here for latest]_
endif::[]

3
upgrading/index.adoc
View file

@ -9,4 +9,7 @@ include::topics/templates/document-attributes-community.adoc[]
= {upgradingguide_name}
:release_header_latest_link: {upgradingguide_link_latest}
include::topics/templates/release-header.adoc[]
include::topics.adoc[]