Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Migrates documentation to Antora #241

Merged
merged 16 commits into from
Sep 8, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions .github/workflows/deploy-docs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
name: Deploy Docs
on:
push:
branches-ignore: [ gh-pages ]
tags: '**'
repository_dispatch:
types: request-build-reference # legacy
#schedule:
#- cron: '0 10 * * *' # Once per day at 10am UTC
workflow_dispatch:
permissions:
actions: write
jobs:
build:
runs-on: ubuntu-latest
# FIXME: enable when pushed to spring-projects
# if: github.repository_owner == 'spring-projects'
steps:
- name: Checkout
uses: actions/checkout@v3
with:
ref: docs-build
fetch-depth: 1
- name: Dispatch (partial build)
if: github.ref_type == 'branch'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD) -f build-refname=${{ github.ref_name }}
- name: Dispatch (full build)
if: github.ref_type == 'tag'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: gh workflow run deploy-docs.yml -r $(git rev-parse --abbrev-ref HEAD)
10 changes: 9 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,12 @@ _site/
.factorypath
.vscode/
.flattened-pom.xml
.DS_Store
.DS_Store
node_modules
node
_configprops.adoc
_spans.adoc
_metrics.adoc
_conventions.adoc
package.json
package-lock.json
63 changes: 12 additions & 51 deletions README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,8 @@ image::https://github.com/spring-cloud/spring-cloud-build/workflows/Build/badge.
Spring Cloud Build is a common utility project for Spring Cloud
to use for plugin and dependency management.

== Building and Deploying
[[building-and-deploying]]
= Building and Deploying

To install locally:

Expand Down Expand Up @@ -45,7 +46,8 @@ $ mvn deploy -P central -DaltReleaseDeploymentRepository=sonatype-nexus-staging:

(the "central" profile is available for all projects in Spring Cloud and it sets up the gpg jar signing, and the repository has to be specified separately for this project because it is a parent of the starter parent which users in turn have as their own parent).

== Contributing
[[contributing]]
= Contributing

:spring-cloud-build-branch: master

Expand Down Expand Up @@ -278,7 +280,8 @@ If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your s
----


== Flattening the POMs
[[flattening-the-poms]]
= Flattening the POMs

To avoid propagating build setup that is required to build a Spring Cloud project, we're using the maven flatten plugin. It has the advantage of letting you use whatever features you need while publishing "clean" pom to the repository.

Expand All @@ -296,7 +299,8 @@ In order to add it, add the `org.codehaus.mojo:flatten-maven-plugin` to your `po
</build>
----

== Reusing the documentation
[[reusing-the-documentation]]
= Reusing the documentation

Spring Cloud Build publishes its `spring-cloud-build-docs` module that contains
helpful scripts (e.g. README generation ruby script) and css, xslt and images
Expand All @@ -305,9 +309,6 @@ approach of generating documentation just add these plugins to your `docs` modul

[source,xml]
----
<properties>
<upload-docs-zip.phase>deploy</upload-docs-zip.phase> <8>
</properties>
<profiles>
<profile>
<id>docs</id>
Expand Down Expand Up @@ -351,8 +352,6 @@ approach of generating documentation just add these plugins to your `docs` modul
<4> This plugin generates an `adoc` file with all the configuration properties from the classpath
<5> This plugin is required to parse the Asciidoctor documentation
<6> This plugin is required to copy resources into proper final destinations and to generate main README.adoc and to assert that no files use unresolved links
<7> This plugin ensures that the generated zip docs will get published
<8> This property turns on the "deploy" phase for <7>

IMPORTANT: The order of plugin declaration is important!

Expand All @@ -362,51 +361,13 @@ If you want to modify which of the configuration properties are put in the table

Spring Cloud Build Docs comes with a set of attributes for asciidoctor that you can reuse.

[source,xml]
[source,yml]
----
<attributes>
<docinfo>shared</docinfo>
<allow-uri-read>true</allow-uri-read>
<nofooter/>
<toc>left</toc>
<toc-levels>4</toc-levels>
<sectlinks>true</sectlinks>
<sources-root>${project.basedir}/src@</sources-root>
<asciidoc-sources-root>${project.basedir}/src/main/asciidoc@</asciidoc-sources-root>
<generated-resources-root>${project.basedir}/target/generated-resources@
</generated-resources-root>
<!-- Use this attribute the reference code from another module -->
<!-- Note the @ at the end, lowering the precedence of the attribute -->
<project-root>${maven.multiModuleProjectDirectory}@</project-root>
<!-- It's mandatory for you to pass the docs.main property -->
<github-repo>${docs.main}@</github-repo>
<github-project>https://github.com/spring-cloud/${docs.main}@</github-project>
<github-raw>
https://raw.githubusercontent.com/spring-cloud/${docs.main}/${github-tag}@
</github-raw>
<github-code>https://github.com/spring-cloud/${docs.main}/tree/${github-tag}@
</github-code>
<github-issues>https://github.com/spring-cloud/${docs.main}/issues/@</github-issues>
<github-wiki>https://github.com/spring-cloud/${docs.main}/wiki@</github-wiki>
<github-master-code>https://github.com/spring-cloud/${docs.main}/tree/master@
</github-master-code>
<index-link>${index-link}@</index-link>

<!-- Spring Cloud specific -->
<!-- for backward compatibility -->
<spring-cloud-version>${project.version}@</spring-cloud-version>
<project-version>${project.version}@</project-version>
<github-tag>${github-tag}@</github-tag>
<version-type>${version-type}@</version-type>
<docs-url>https://docs.spring.io/${docs.main}/docs/${project.version}@</docs-url>
<raw-docs-url>${github-raw}@</raw-docs-url>
<project-version>${project.version}@</project-version>
<project-name>${docs.main}@</project-name>
<source-highlighter>highlight.js</source-highlighter>
</attributes>
Unresolved directive in <stdin> - include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/main/docs/src/main/antora/resources/antora-resources/antora.yml[indent=0]
----

== Updating the guides
[[updating-the-guides]]
= Updating the guides

We assume that your project contains guides under the `guides` folder.

Expand Down
38 changes: 38 additions & 0 deletions docs/antora-playbook.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
antora:
extensions:
- '@springio/antora-extensions/partial-build-extension'
- require: '@springio/antora-extensions/latest-version-extension'
- require: '@springio/antora-extensions/inject-collector-cache-config-extension'
- '@antora/collector-extension'
- '@antora/atlas-extension'
- require: '@springio/antora-extensions/root-component-extension'
root_component_name: 'cloud-build'
site:
title: Spring Cloud Build
url: https://docs.spring.io/spring-cloud-build/reference/
content:
sources:
- url: ./..
branches: HEAD
start_path: docs
worktrees: true
asciidoc:
attributes:
page-stackoverflow-url: https://stackoverflow.com/tags/spring-cloud
page-pagination: ''
hide-uri-scheme: '@'
tabs-sync-option: '@'
chomp: 'all'
extensions:
- '@asciidoctor/tabs'
- '@springio/asciidoctor-extensions'
sourcemap: true
urls:
latest_version_segment: ''
runtime:
log:
failure_level: warn
format: pretty
ui:
bundle:
url: https://github.com/spring-io/antora-ui-spring/releases/download/v0.3.5/ui-bundle.zip
12 changes: 12 additions & 0 deletions docs/antora.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
name: cloud-build
version: true
title: Spring Cloud Build
nav:
- modules/ROOT/nav.adoc
ext:
collector:
run:
command: ./mvnw validate process-resources -Pdocs -pl docs
local: true
scan:
dir: ./target/classes/antora-resources/
3 changes: 3 additions & 0 deletions docs/modules/ROOT/nav.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
* xref:index.adoc[]
* xref:building.adoc[]
* xref:contributing.adoc[]
4 changes: 4 additions & 0 deletions docs/modules/ROOT/pages/building.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[[building]]
= Building

include::partial$building.adoc[]
4 changes: 4 additions & 0 deletions docs/modules/ROOT/pages/contributing.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[[contributing]]
= Contributing

include::partial$contributing.adoc[]
4 changes: 4 additions & 0 deletions docs/modules/ROOT/pages/index.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[[overview]]
= Overview

Spring Cloud Build is a common utility project for Spring Cloud to use for plugin and dependency management.
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
:jdkversion: 17

=== Basic Compile and Test
[[basic-compile-and-test]]
== Basic Compile and Test

To build the source you will need to install JDK {jdkversion}.

Expand All @@ -27,31 +28,36 @@ source control.
The projects that require middleware (i.e. Redis) for testing generally
require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running.


=== Documentation
[[documentation]]
== Documentation

The spring-cloud-build module has a "docs" profile, and if you switch
that on it will try to build asciidoc sources from
`src/main/asciidoc`. As part of that process it will look for a
`README.adoc` and process it by loading all the includes, but not
that on it will try to build asciidoc sources using https://docs.antora.org/antora/latest/[Antora] from
`modules/ROOT/`.

As part of that process it will look for a
`docs/src/main/asciidoc/README.adoc` and process it by loading all the includes, but not
parsing or rendering it, just copying it to `${main.basedir}`
(defaults to `${basedir}`, i.e. the root of the project). If there are
(defaults to `$\{basedir}`, i.e. the root of the project). If there are
any changes in the README it will then show up after a Maven build as
a modified file in the correct place. Just commit it and push the change.

=== Working with the code
[[working-with-the-code]]
== Working with the code
If you don't have an IDE preference we would recommend that you use
https://www.springsource.com/developer/sts[Spring Tools Suite] or
https://eclipse.org[Eclipse] when working with the code. We use the
https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
should also work without issue as long as they use Maven 3.3.3 or better.

==== Activate the Spring Maven profile
[[activate-the-spring-maven-profile]]
=== Activate the Spring Maven profile
Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
the spring milestone and snapshot repositories. Use your preferred IDE to set this
profile to be active, or you may experience build errors.

==== Importing into eclipse with m2eclipse
[[importing-into-eclipse-with-m2eclipse]]
=== Importing into eclipse with m2eclipse
We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse
marketplace".
Expand All @@ -65,7 +71,8 @@ add the "spring" profile to your `settings.xml`. Alternatively you can
copy the repository settings from the "spring" profile of the parent
pom into your `settings.xml`.

==== Importing into eclipse without m2eclipse
[[importing-into-eclipse-without-m2eclipse]]
=== Importing into eclipse without m2eclipse
If you prefer not to use m2eclipse you can generate eclipse project metadata using the
following command:

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@

= Contributor Code of Conduct
[[contributor-code-of-conduct]]
== Contributor Code of Conduct

As contributors and maintainers of this project, and in the interest of fostering an open
and welcoming community, we pledge to respect all people who contribute through reporting
Expand Down Expand Up @@ -42,4 +42,4 @@ with regard to the reporter of an incident.

This Code of Conduct is adapted from the
https://contributor-covenant.org[Contributor Covenant], version 1.3.0, available at
https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/]
https://contributor-covenant.org/version/1/3/0/[contributor-covenant.org/version/1/3/0/]
Original file line number Diff line number Diff line change
@@ -1 +1 @@
NOTE: Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at {github-project}[github].
NOTE: Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like to contribute to this section of the documentation or if you find an error, please find the source code and issue trackers in the project at {github-project}[github].
Loading
Loading