Skip to content

Commit 8422f0f

Browse files
rwinchrwinch
committed
Initial
1 parent dc3c016 commit 8422f0f

11 files changed

+628
-0
lines changed

Diff for: ‎.github/workflows/deploy-docs.yml

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Deploy Docs
2+
run-name: ${{ format('{0} ({1})', github.workflow, github.event.inputs.build-refname || 'all') }}
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
build-refname:
7+
description: Enter git refname to build (e.g., 5.7.x).
8+
required: false
9+
push:
10+
branches: docs-build
11+
env:
12+
GRADLE_ENTERPRISE_SECRET_ACCESS_KEY: ${{ secrets.GRADLE_ENTERPRISE_SECRET_ACCESS_KEY }}
13+
permissions: read-all
14+
jobs:
15+
build:
16+
if: github.repository_owner == 'spring-projects'
17+
runs-on: ubuntu-latest
18+
steps:
19+
- name: Checkout
20+
uses: actions/checkout@v3
21+
with:
22+
fetch-depth: 5
23+
- name: Set Up Gradle
24+
uses: spring-io/spring-gradle-build-action@v2
25+
with:
26+
java-version: '17'
27+
distribution: temurin
28+
- name: Set up refname build
29+
if: github.event.inputs.build-refname
30+
run: |
31+
git fetch --depth 1 https://github.com/$GITHUB_REPOSITORY ${{ github.event.inputs.build-refname }}
32+
echo BUILD_REFNAME=${{ github.event.inputs.build-refname }} >> $GITHUB_ENV
33+
echo BUILD_VERSION=$(git cat-file --textconv FETCH_HEAD:gradle.properties | sed -n '/^version=/ { s/^version=//;p }') >> $GITHUB_ENV
34+
- name: Run Antora
35+
run: ./gradlew antora
36+
- name: Publish Docs
37+
uses: spring-io/spring-doc-actions/[email protected]
38+
with:
39+
docs-username: ${{ secrets.DOCS_USERNAME }}
40+
docs-host: ${{ secrets.DOCS_HOST }}
41+
docs-ssh-key: ${{ secrets.DOCS_SSH_KEY }}
42+
docs-ssh-host-key: ${{ secrets.DOCS_SSH_HOST_KEY }}

Diff for: ‎.sdkmanrc

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Use sdkman to run "sdk env" to initialize with correct JDK version
2+
# Enable auto-env through the sdkman_auto_env config
3+
# See https://sdkman.io/usage#config
4+
# A summary is to add the following to ~/.sdkman/etc/config
5+
# sdkman_auto_env=true
6+
java=17.0.3-tem

Diff for: ‎README.adoc

+140
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
= Spring Framework Docs Build
2+
3+
You're currently viewing the Antora playbook branch.
4+
The playbook branch hosts the docs build that is used to build and publish the production docs site.
5+
6+
The Spring Framework reference docs are built using https://antora.org[Antora].
7+
This README covers how to build the docs in a software branch as well as how to build the production docs site locally.
8+
9+
== Overview
10+
11+
To prepare your system for building the documentation, <<prerequisites,install the prerequisites>> and then <<build-main,create your workspace and build the main branch documentation>>.
12+
Once you've completed those steps, follow the instructions in <<build-branch,Build the 6.0.x branch documentation>> to learn how to build the documentation for a version branch you haven't previously checked out.
13+
14+
To build the production site documentation on your computer, follow the instructions in <<prerequisites,Prerequisites>>, <<build-main,Build the main branch documentation>>, and then <<build-production,Build the production documentation site>>.
15+
16+
.Branch checkout instead of worktrees
17+
[NOTE]
18+
====
19+
If you prefer to set up your workspace without worktrees, complete the steps in <<prerequisites,Prerequisites>> and clone the project repository onto your computer.
20+
Then follow the instructions in each section starting from the `sdk env || sdk env install` step once you've checked out the desired branch.
21+
====
22+
23+
[#prerequisites]
24+
== Prerequisites (everyone)
25+
26+
These instructions assume you already have basic tools on your system, including bash, zip, unzip, git, and curl.
27+
In addition to these basic tools, you need https://sdkman.io/install[SDKMAN!] installed so that the correct JDK is set for each branch.
28+
29+
. Open your terminal and enter the following command:
30+
+
31+
--
32+
$ curl -s "https://get.sdkman.io" | bash
33+
34+
This command downloads and installs SDKMAN!
35+
Once installation is complete, you should see a command displayed in your terminal that will initiate SDKMAN.
36+
--
37+
38+
. Copy the command displayed in your terminal and run it.
39+
`$HOME` is the path unique to your computer (e.g., _home/my-jam/.sdkman/bin/sdkman-init.sh_).
40+
41+
$ source "$HOME/.sdkman/bin/sdkman-init.sh"
42+
43+
You'll use SDKMAN in the next sections to install and switch to the JDK required for each branch.
44+
Now you're ready to <<build-main,create your workspace>>.
45+
46+
[#build-main]
47+
== Build the main branch documentation (writers)
48+
49+
Your workspace will be the folder that contains the git worktrees of the project.
50+
51+
. In your terminal, create a directory for the project and then change into that directory.
52+
53+
$ mkdir spring-framework
54+
$ cd spring-framework
55+
56+
. Clone the project repository and create the primary worktree for the main branch.
57+
Then change into the new _main_ folder.
58+
59+
$ git clone https://github.com/spring-projects/spring-framework main
60+
$ cd main
61+
62+
. Switch to the required JDK using SDKMAN by running the following command:
63+
+
64+
--
65+
$ sdk env || sdk env install
66+
67+
SDKMAN will switch to the required JDK or install it if it isn't present.
68+
--
69+
70+
. Generate the documentation with Antora using the following command:
71+
+
72+
--
73+
$ ./gradlew -PbuildSrc.skipTests=true :framework-docs:antora
74+
75+
This command will build the documentation, including any generated attributes, for the main branch.
76+
--
77+
78+
. Navigate to _$HOME/spring-framework/main/framework-docs/build/site/index.html_ to view the generated documentation.
79+
80+
[#build-branch]
81+
== Build the 6.0.x branch documentation (writers)
82+
83+
NOTE: The instructions in this section assume you've completed the steps in the <<build-main,previous section>>.
84+
85+
After creating the worktree for the main branch, you can set up a worktree for any other branches you'll work on in the future.
86+
In this section, you'll create a worktree for the 6.0.x branch in your project workspace.
87+
88+
. To add a worktree, you have to be in a worktree.
89+
In your terminal, change to the _main_ folder if you aren't already in it, e.g., _$HOME/spring-framework/main_.
90+
Set up a worktree for the 6.0.x branch and then change into the new directory by running the following commands:
91+
92+
$ git worktree add ../6.0.x 6.0.x --track
93+
$ cd ../6.0.x
94+
95+
. Switch to the required JDK or install it.
96+
97+
$ sdk env || sdk env install
98+
99+
. Generate the documentation with the following command:
100+
+
101+
--
102+
$ ./gradlew -PbuildSrc.skipTests=true :framework-docs:antora
103+
104+
This command will build the documentation, including any generated attributes, for the 6.0.x branch.
105+
--
106+
107+
. Navigate to _$HOME/spring-framework/6.0.x/docs/build/site/index.html_ to view the generated documentation.
108+
109+
[#build-production]
110+
== Build the production documentation site (docs manager)
111+
112+
NOTE: The instructions in this section assume you've <<build-main,prepared your workspace and created the worktree for the main branch>>.
113+
114+
To build the project's production site, you'll set up a worktree for the docs-build branch of the repository.
115+
116+
. To add a worktree, you have to be in a worktree.
117+
In your terminal, change to the _main_ folder if you aren't already in it, e.g., _$HOME/spring-framework/main_.
118+
Run the following command to set up the worktree for the _docs-build_ branch.
119+
Then change into the new _docs-build_ directory.
120+
121+
$ git worktree add ../docs-build docs-build --track
122+
$ cd ../docs-build
123+
124+
. Switch to the required JDK or install it.
125+
126+
$ sdk env || sdk env install
127+
128+
. Generate the documentation for the project's production site using the following command:
129+
+
130+
--
131+
$ ./gradlew antora
132+
133+
This command will build all of the documentation included in the project's production site from the repository on GitHub.
134+
135+
To build the documentation from the current clone, using any worktrees that are available, use the following command instead:
136+
137+
$ ./gradlew antora --playbook local-antora-playbook.yml
138+
--
139+
140+
. Navigate to _$HOME/spring-framework/docs-site/build/site/index.html_ to view the generated documentation.

Diff for: ‎antora-playbook.yml

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
antora:
2+
extensions:
3+
- '@antora/collector-extension'
4+
- '@antora/atlas-extension'
5+
- '@opendevise/antora-release-line-extension'
6+
- '@springio/antora-extensions/latest-version-extension'
7+
- require: '@springio/antora-extensions/root-component-extension'
8+
root_component_name: 'framework'
9+
site:
10+
title: Spring Framework
11+
url: https://docs.spring.io/spring-security/reference
12+
robots: allow
13+
git:
14+
ensure_git_suffix: false
15+
content:
16+
sources:
17+
- url: https://github.com/rwinch/spring-framework
18+
branches: [6.0.x]
19+
start_path: framework-docs
20+
asciidoc:
21+
extensions:
22+
- '@asciidoctor/tabs'
23+
- '@springio/asciidoctor-extensions'
24+
- '@springio/asciidoctor-extensions/include-code-extension'
25+
attributes:
26+
page-pagination: ''
27+
hide-uri-scheme: '@'
28+
include-java: 'example$docs-src/main/java/org/springframework/docs'
29+
urls:
30+
latest_version_segment_strategy: redirect:to
31+
latest_version_segment: ''
32+
redirect_facility: httpd
33+
runtime:
34+
log:
35+
failure_level: warn
36+
ui:
37+
bundle:
38+
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.2.2/ui-bundle.zip
39+
snapshot: true

Diff for: ‎build.gradle

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
plugins {
2+
id 'base'
3+
id 'org.antora' version '1.0.0'
4+
}
5+
6+
antora {
7+
version = '3.2.0-alpha.2'
8+
options = ['--clean', '--fetch', '--stacktrace']
9+
environment = [
10+
'ALGOLIA_API_KEY': '042f6aaab6ce998d2ea29e60167e1660',
11+
'ALGOLIA_APP_ID': 'WB1FQYI187',
12+
'ALGOLIA_INDEX_NAME': 'springframework'
13+
]
14+
// NOTE remember to update the versions in lib/antora/templates/per-branch-antora-playbook.yml as well
15+
dependencies = [
16+
'@antora/atlas-extension': '1.0.0-alpha.1',
17+
'@antora/collector-extension': '1.0.0-alpha.3',
18+
'@asciidoctor/tabs': '1.0.0-beta.3',
19+
'@opendevise/antora-release-line-extension': '1.0.0',
20+
'@springio/antora-extensions': '1.3.0',
21+
'@springio/asciidoctor-extensions': '1.0.0-alpha.9',
22+
]
23+
}

Diff for: ‎gradle.properties

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
group=org.springframework
2+
description=Spring Framework Docs Site

Diff for: ‎gradle/wrapper/gradle-wrapper.jar

59.3 KB
Binary file not shown.

Diff for: ‎gradle/wrapper/gradle-wrapper.properties

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
distributionBase=GRADLE_USER_HOME
2+
distributionPath=wrapper/dists
3+
distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
4+
zipStoreBase=GRADLE_USER_HOME
5+
zipStorePath=wrapper/dists

0 commit comments

Comments
 (0)