Guide Rewrite

[robertmcnees]

This is a rewrite of the guide with many changes. In addition to content changes, structural changes were made to the guide as a potential template for future guide updates to follow.

Addresses issues #33, #32, #31, #29, #28.

Several changes were made to promote correctness, make for a better user experience, and allow the option to dual publish to Spring Academy in the future.

• The README.adoc has no text content, but instead links to 3 separate files. This allows spring.io/guides to publish the guide with the full context, including Spring Initializr, while allowing Spring Academy to only be concerned with the guide specific content, located in content.adoc. There should be no change for how users view the guide on spring.io.
• The README.adoc added an additional conditional section that can be set if rendering for Spring Academy to exclude certain sections.
• The initial and complete folders were removed in favor of keeping only the solution in the root project directory. This should simplify the user experience by providing fewer places to look for code and create an easier experience when importing the project to an IDE. The user can still follow along with a blank project by starting with Spring Initializr. This format of keeping the code in the root directory makes it possible to easily load the project to Spring Academy as well.
• A single build tool is used. For this guide, Gradle is used because it is the preferred build tool of the project driving the functionality of the guide, Spring Framework. Having a single build tool should simplify the user experience when importing the project to a local IDE. This ease of import is also important for the user experience when loading into Spring Academy.
• A lot of references to the common macros project were removed. This was done to prioritize correctness and user experience over ease of guide creation. A few problems exist when trying to use a common template. First, the wording may be slightly off, as demonstrated by issue #33. The 'web' text in the line This web application is 100% pure Java... comes from a common file. Second, some teachings were incorrect. For example, in the popular rest-service guide, we advise the user that @ComponentScan will check the com/example package, but that information is not correct. It will in fact check the com/example/restservice package in this particular guide. Third, the commands to package the application as a jar file were not correct. The problem is persistent to all guides as described here.
• References to dated technologies, i.e. web.xml and WAR files, were also removed. This was done when removing links to the common GitHub macro repository in favor of static text.
• The Build an executable JAR section was renamed to Building the Application and text was added for using Cloud Native Buildpacks and Native Image compilation.
• Added a new workflow action to run asciidoc reducer on the README.adoc file and check in a new file. This reducer action is a prerequisite to converting to markdown for future use on Spring Academy.

[robertmcnees]

I think that instead of 3 separate files, using ifndef from AsciiDoc Conditionals would be a better approach.

If we choose to publish this guide to Spring Academy, we could set the variable env-exclude-spring-initializr to exclude certain sections. This can easily be achieved using a downdoc command:

npx downdoc -a env-exclude-spring-initializr README.adoc

@Buzzardo what do you think about this use of a conditional? @joemoore do you think an approach could work for Spring Academy?

EDIT: The command above will not work correctly when using include statements. An prerequisite step is to use asciidoc reducer.

[robertmcnees]

Converted to draft until I come up with a better solution to importing some common components from the getting started macros GitHub repository. Thanks for the feedback @mbhave!

[robertmcnees]

I added a new file to the getting-started-macros repository that is intended to be a common section at the end of every guide.

[robertmcnees]

The 3 files in this PR can be checked into the common macro project at a later date.

• guide_intro.adoc
• spring_academy_intro.adoc
• spring_academy_see_also.adoc

Before those files are checked into the macro project and used as a template for all guides to follow, I'd like to verify that the process to convert content to Spring Academy (reducer, downdoc) is successful. This requires a GitHub action to execute, which should be performed on a non-forked repo.