The custom stylesheet used with JDK 8 no longer works with JDK 17.
Thus in order to make the generated Javadoc usable, we are disabling
the custom stylesheet for the time being.
See gh-27496
In order to catch Javadoc errors in the build, we now enable the
`Xwerror` flag for the `javadoc` tool. In addition, we now use
`Xdoclint:syntax` instead of `Xdoclint:none` in order to validate
syntax within our Javadoc.
This commit fixes all resulting Javadoc errors and warnings.
This commit also upgrades to Undertow 2.2.12.Final and fixes the
artifact names for exclusions for the Servlet and annotations APIs.
The incorrect exclusion of the Servlet API resulted in the Servlet API
being on the classpath twice for the javadoc task, which resulted in the
following warnings in previous builds.
javadoc: warning - Multiple sources of package comments found for package "javax.servlet"
javadoc: warning - Multiple sources of package comments found for package "javax.servlet.http"
javadoc: warning - Multiple sources of package comments found for package "javax.servlet.descriptor"
javadoc: warning - Multiple sources of package comments found for package "javax.servlet.annotation"
Closes gh-27480
A side effect of 71995a9087 caused the
dynamic table of contents in the left-hand side navigation to no longer
be displayed, likely due to the missing "details" DIV.
This commit addresses this issue by applying the custom header only to
index.adoc.
Consequently, the TOC is now displayed again on all pages except the
index page, but the customized header is no longer applied to those
pages.
We may revisit this issue if we decide that we want the custom header
on all pages (and not just the index page).
Closes gh-27177
This commit defines the doc-root and api-spring-framework attributes
once in docs.gradle instead of duplicating them in each *.adoc file.
This commit also introduces a new docs-spring-framework global
attribute.
This commit disables the automatic header generation from Asciidoc's
default template and replaces it with a custom header that omits the
"Version" label before the revision number. The revision number is also
displayed in a simple span tag in order to reduce the amount of
vertical space taken by the header.
Prior to this commit, the `docsZip` task would not reference the new
output locations for the `asciidoctor` and `asciidoctorPdf` tasks.
This results with missing reference docs in the docs zip.
This commit updates the input locations of the Zip task to include the
produced reference docs.
Fixes gh-25783
Prior to this commit, the asciidoctor Gradle task was configured to
generate both the HTML5 and PDF backends. Unfortunately, this resulted
in resources such as HTML, JavaScript, CSS, and images being published
alongside the generated PDF documents.
This commit addresses this issue by introducing the use of a dedicated
asciidoctorPdf Gradle task. The existing asciidoctor Gradle task has
been modified to only generate HTML5 output. Both of these tasks now
share common configuration supplied by the updated asciidoctorj Gradle
task.
In addition, the asciidoctor task now depends on the asciidoctorPdf
task. Thus, invoking `./gradlew asciidoctor` will still generate both
the HTML5 and PDF outputs; whereas, `./gradlew asciidoctorPdf` will
generate only the PDF outputs. We may later decide to rework the tasks
to introduce a dedicated asciidoctorHtml task so that we can generate
the HTML outputs without having to generate the PDF outputs (which are
more time consuming).
See gh-25783
Prior to this commit, the asciidoctor Gradle task was configured to
generate both the HTML5 and PDF backends. Unfortunately, this resulted
in resources such as HTML, JavaScript, CSS, and images being published
alongside the generated PDF documents.
This commit addresses this issue by introducing the use of a dedicated
asciidoctorPdf Gradle task. The existing asciidoctor Gradle task has
been modified to only generate HTML5 output. Both of these tasks now
share common configuration supplied by the updated asciidoctorj Gradle
task.
In addition, the asciidoctor task now depends on the asciidoctorPdf
task. Thus, invoking `./gradlew asciidoctor` will still generate both
the HTML5 and PDF outputs; whereas, `./gradlew asciidoctorPdf` will
generate only the PDF outputs. We may later decide to rework the tasks
to introduce a dedicated asciidoctorHtml task so that we can generate
the HTML outputs without having to generate the PDF outputs (which are
more time consuming).
See gh-25783
This is done:
- For consistency with other Spring projects
- Because it is probably a better option to use reference instead of
spring-framework-reference (spring-framework is already present in
the URL)
- To improve PDF documentation discoverability
As a consequence:
- spring-framework-reference HTML documentation is now published
under reference/html
- spring-framework-reference/pdf PDF documentation is now published
under reference/pdf
The following permanent redirect should be created before Spring
Framework 5.3.0 release:
- current/spring-framework-reference/pdf/* to current/reference/pdf/*
- current/spring-framework-reference/* to current/reference/html/*
Closes gh-25071
The `images` folder contains some files used to create the images, such
as OmniGraffle and SVG.
This commit modifies the `include` pattern to ensure that only `*.png`
files are copied from the source folder to the published reference
manual.
This commit updates the spring-doc-resources version to 0.2.0 to get the
latest look and feel in the HTML version of the reference manual.
Closes gh-24831
0.4.0 provides built-in support for remembering a user's selections
using local storage. This replaces the custom switch language
JavaScript.
The selection is stored using a key derived from the
options that were available. Concretely, when the options are Java or
Kotlin, the local storage key is java-kotlin. Similarly, if the
choices were Java, Kotlin, and XML, the key would be java-kotlin-xml.
Given local storage's domain and protocol scoping, the nature of the
key that's used for storage will allow a user's selections to be
applied across all documentation hosted on https://docs.spring.io that
offer the same options.
Closes gh-24481
Previously, the Asciidoctor task was not cacheable and generating the
PDF documentation was very slow. To improve build times, the PDF
documentation was not generated for snapshot builds.
The upgrade to 2.4.0 of the Asciidoctor Gradle pluging means that the
Asciidoctor task is now cacheable. As such, its tasks will only run
when the documentation has changed. This should allow PDF
documentation to be published for every build without slowing things
down too much and the cost of generating the documentation will only
be incurred when there is a change to the documentation.
See gh-24216
This commit updates the build to use the latest version of the
Asciidoctor Gradle Plugin. One significant new feature is that the
plugin's tasks are now cacheable.
Closes gh-24216
Prior to this commit, the schemaZip Gradle task failed to find Spring
schema files on MS Windows due to path separators hard coded to forward
slashes that are not compatible with the Windows operating system.
Consequently, a full build failed on Windows since the distZip task was
not able to locate the zipped schema archive that the schemaZip task
failed to create.
This commit fixes this by updating the schemaZip task to search for
schema files using backslashes as well as forward slashes.
Closes gh-23933
This commit configures the Gradle Download plugin that's used a build
step when generating the reference documentation. Here we're making sure
that the task is caching and reusing the resource if it's been
downloaded already.
See gh-23282
Prior to this commit, the reference documentation build with asciidoctor
would get the common "spring-docs-resources" as a dependency and then
use it when generating the docs.
As seen in #23124, this can cause problems since we'd like to
consistently resolve our dependencies. In this case, the
"spring-doc-resources" archive is not published on maven central since
it's not officially supported by the Spring team as an open source
project.
This commit updates the reference documentation build to get this
archive as a simple download task and avoid resolving it as a
dependency.
See gh-23282
This commit reorganizes tasks and scripts in the build to only apply
them where they're needed. We're considering here 3 "types" of projects
in our build:
* the root project, handling documentation, publishing, etc
* framework modules (a project that's published as a spring artifact)
* internal modules, such as the BOM, our coroutines support and our
integration-tests
With this change, we're strealining the project configuration for all
spring modules and only applying plugins when needed (typically our
kotlin support).
See gh-23282
This commit introduces Kotlin code snippets, for now
in the core reference documentation. Other sections
will follow, as well as improvements like global
language switch.
See gh-21778
This commit removes the custom static resources for the reference
documentation and instead uses the new Spring Doc Resources project
https://github.com/spring-io/spring-doc-resources
The asciidoctor theme is now shared between Spring projects and
integrated in the project build.
Sam Brannen
Brian Clozel
Arjen Poutsma
Sébastien Deleuze
Sam Brannen
Brian Clozel
Sam Brannen
Jay Bryant
Sébastien Deleuze
Andy Wilkinson
Rob Winch
YuDongYing
Stephane Nicoll
Spring Operator
Spring Operator