search

spring-cloud / spring-cloud-release

Spring Cloud Release Train - dependency management across a wide range of Spring Cloud projects.
http://projects.spring.io/spring-cloud
Apache License 2.0
874 stars 179 forks source link

Question: How to build train-docs successfully? #254

Closed supermanHub closed 1 year ago

supermanHub commented 1 year ago

Hi dear, I am working on an offline environment, and have to deploy train-docs to my local machine. But I don't get succeed! Some errors always happen, could anybody give me some help? Thank you very much.

What I did

Environment is AlmaLinux 9 && OpenJDK 17

git clone https://github.com/spring-cloud/spring-cloud-release.git
cd spring-cloud-release // which branch is correct?
git checkout v2021.0.5
./mvnw clean install -Pdocs,train-docs -pl train-docs

Errors

[INFO] --- asciidoctor-maven-plugin:2.1.0:process-asciidoc (generate-pdf-documentation) @ spring-cloud-docs ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 0 resource
[INFO] asciidoctor: ERROR: cs/spring-cloud-build/docs/src/main/asciidoc/spring-cloud-build.adoc: line 1: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: ERROR: cs/spring-cloud-build/docs/src/main/asciidoc/README.adoc: line 43: include uri not readable: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/docs/src/main/asciidoc/contributing.adoc
[INFO] asciidoctor: DEBUG: cs/spring-cloud-build/docs/src/main/asciidoc/README.adoc: line 43: unknown name for block macro: 
[INFO] asciidoctor: ERROR: cs/spring-cloud-build/docs/src/main/asciidoc/README.adoc: line 131: include uri not readable: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/3.1.x/pom.xml
[INFO] asciidoctor: ERROR: cs/spring-cloud-bus/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: ERROR: cs/spring-cloud-bus/docs/src/main/asciidoc/spring-cloud-bus.adoc: line 6: include uri not readable: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc
[INFO] asciidoctor: DEBUG: cs/spring-cloud-bus/docs/src/main/asciidoc/spring-cloud-bus.adoc: line 6: unknown name for block macro: 
[INFO] asciidoctor: ERROR: cs/spring-cloud-circuitbreaker/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: ERROR: cs/spring-cloud-circuitbreaker/docs/src/main/asciidoc/spring-cloud-circuitbreaker.adoc: line 22: include uri not readable: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc
[INFO] asciidoctor: DEBUG: spring-cloud.pdfadoc: line 59: unknown name for block macro: 
[INFO] asciidoctor: ERROR: spring-cloud.pdfadoc: line 63: include file not found: /home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-cli/docs/src/main/asciidoc/spring-cloud-cli.adoc
[INFO] asciidoctor: DEBUG: spring-cloud.pdfadoc: line 63: unknown name for block macro: 
[INFO] asciidoctor: ERROR: spring-cloud.pdfadoc: line 67: include file not found: /home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-cloudfoundry/docs/src/main/asciidoc/spring-cloud-cloudfoundry.adoc
[INFO] asciidoctor: DEBUG: spring-cloud.pdfadoc: line 67: unknown name for block macro: 
[INFO] asciidoctor: ERROR: cs/spring-cloud-commons/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: WARN: cs/spring-cloud-commons/docs/src/main/asciidoc/spring-cloud-commons.adoc: line 1045: id assigned to block already in use: health-check-based-custom-loadbalancer-configuration
[INFO] asciidoctor: ERROR: cs/spring-cloud-config/docs/src/main/asciidoc/spring-cloud-config.adoc: line 1: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: WARN: cs/spring-cloud-config/docs/src/main/asciidoc/spring-cloud-config.adoc: line 1926: list item index: expected 1, got 2
[INFO] asciidoctor: ERROR: cs/spring-cloud-consul/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: WARN: cs/spring-cloud-consul/docs/src/main/asciidoc/spring-cloud-consul.adoc: line 361: id assigned to section already in use: config-data-import
[INFO] asciidoctor: ERROR: cs/spring-cloud-contract/docs/src/main/asciidoc/spring-cloud-contract.adoc: line 2: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: ERROR: cs/spring-cloud-function/docs/src/main/asciidoc/spring-cloud-function.adoc: line 1: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: ERROR: cs/spring-cloud-function/docs/src/main/asciidoc/spring-cloud-function.adoc: line 19: include uri not readable: https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing-docs.adoc
[INFO] asciidoctor: DEBUG: cs/spring-cloud-function/docs/src/main/asciidoc/spring-cloud-function.adoc: line 19: unknown name for block macro: 
[INFO] asciidoctor: WARN: cs/spring-cloud-function/docs/src/main/asciidoc/spring-cloud-function.adoc: line 708: section title out of sequence: expected level 2, got level 3
[INFO] asciidoctor: WARN: cs/spring-cloud-function/docs/src/main/asciidoc/functional.adoc: line 131: section title out of sequence: expected level 2, got level 4
[INFO] asciidoctor: WARN: cs/spring-cloud-function/docs/src/main/asciidoc/functional.adoc: line 146: section title out of sequence: expected level 2, got level 4
[INFO] asciidoctor: WARN: cs/spring-cloud-function/docs/src/main/asciidoc/adapters/aws-intro.adoc: line 300: section title out of sequence: expected level 4, got level 5
[INFO] asciidoctor: ERROR: cs/spring-cloud-gateway/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: DEBUG: cs/spring-cloud-gateway/docs/src/main/asciidoc/spring-cloud-gateway.adoc: line 2435: unknown style for listing block: soure
[INFO] asciidoctor: WARN: cs/spring-cloud-gateway/docs/src/main/asciidoc/spring-cloud-gateway.adoc: line 2585: id assigned to section already in use: gateway-route-filters
[INFO] asciidoctor: ERROR: spring-cloud.pdfadoc: line 95: include file not found: /home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-kubernetes/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc
[INFO] asciidoctor: DEBUG: spring-cloud.pdfadoc: line 95: unknown name for block macro: 
[INFO] asciidoctor: ERROR: spring-cloud.pdfadoc: line 99: include file not found: /home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-netflix/docs/src/main/asciidoc/spring-cloud-netflix.adoc
[INFO] asciidoctor: DEBUG: spring-cloud.pdfadoc: line 99: unknown name for block macro: 
[INFO] asciidoctor: ERROR: cs/spring-cloud-openfeign/docs/src/main/asciidoc/_attributes.adoc: level 0 sections can only be used when doctype is book
[INFO] asciidoctor: WARN: spring-cloud.pdfadoc: line 123: unterminated listing block
[INFO] asciidoctor: WARN: could not embed image: /tmp/image-20221128-29621-fe0p0w.svg?branch=main&style=svg; image file is an unrecognised format; install prawn-gmagick gem to add support
[INFO] asciidoctor: ERROR: failed to parse formatted text: <a href="https://github.com/spring-cloud/spring-cloud-build/actions">[Build]</a> | <em>https://github.com/spring-cloud/spring-cloud-build/workflows/Build/badge.svg?branch=main&style=svg</em>
[INFO] asciidoctor: ERROR: failed to parse formatted text: Unresolved directive in spring-cloud.pdfadoc - include::/home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-cli/docs/src/main/asciidoc/spring-cloud-cli.adoc[leveloffset&#x3D;+1]
[INFO] asciidoctor: ERROR: failed to parse formatted text: Unresolved directive in spring-cloud.pdfadoc - include::/home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-cloudfoundry/docs/src/main/asciidoc/spring-cloud-cloudfoundry.adoc[leveloffset&#x3D;+1]
[INFO] asciidoctor: INFO: possible invalid reference: load-balancer-exchange-filter-functionload-balancer-exchange-filter-function
[INFO] asciidoctor: INFO: possible invalid reference: _vault_server
[INFO] asciidoctor: WARN: could not retrieve remote image: https://raw.githubusercontent.com/spring-cloud/spring-cloud/0e57818ec79894d338c3936459fb7834eeea5f50/docs/src/main/asciidoc/images/AWS-deploy.png; 404 Not Found
[INFO] asciidoctor: INFO: possible invalid reference: Custom Runtime
[INFO] asciidoctor: WARN: image to embed not found or not readable: /home/wwang/Git/spring-cloud-release/train-docs/target/train-docs/spring_cloud_gateway_diagram.png
[INFO] asciidoctor: ERROR: failed to parse formatted text: Unresolved directive in spring-cloud.pdfadoc - include::/home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-kubernetes/docs/src/main/asciidoc/spring-cloud-kubernetes.adoc[leveloffset&#x3D;+1]
[INFO] asciidoctor: ERROR: failed to parse formatted text: Unresolved directive in spring-cloud.pdfadoc - include::/home/wwang/Git/spring-cloud-release/train-docs/target/unpacked-docs/spring-cloud-netflix/docs/src/main/asciidoc/spring-cloud-netflix.adoc[leveloffset&#x3D;+1]
[INFO] asciidoctor: ERROR: failed to parse formatted text: spring.cloud.vault: authentication: AWS_EC2 aws-ec2: role: application-server aws-ec2-path: aws-ec2 identity-document: <a href="http://&#8230;&#8203" class="bare">&#​8230;&#​8203</a>; nonce: my-static-nonce
[INFO] Converted /home/wwang/Git/spring-cloud-release/train-docs/target/train-docs/spring-cloud.pdfadoc
[INFO] 
[INFO] --- maven-antrun-plugin:3.0.0:run (readme) @ spring-cloud-docs ---
[INFO] Executing tasks
WARNING: A terminally deprecated method in java.lang.System has been called
WARNING: System::setSecurityManager has been called by org.apache.tools.ant.types.Permissions (file:/home/wwang/.m2/repository/org/apache/ant/ant/1.9.14/ant-1.9.14.jar)
WARNING: Please consider reporting this to the maintainers of org.apache.tools.ant.types.Permissions
WARNING: System::setSecurityManager will be removed in a future release
Will do the Readme conversion from [/home/wwang/Git/spring-cloud-release/train-docs/src/main/asciidoc/README.adoc] to [/home/wwang/Git/spring-cloud-release/train-docs/../README.adoc]
There's no file [/home/wwang/Git/spring-cloud-release/train-docs/src/main/asciidoc/README.adoc], skipping readme generation
[INFO] Executed tasks
[INFO] 
[INFO] --- maven-antrun-plugin:3.0.0:run (assert-no-unresolved-links) @ spring-cloud-docs ---
[INFO] Executing tasks
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  13:31 min
[INFO] Finished at: 2022-11-28T19:10:37+08:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-antrun-plugin:3.0.0:run (assert-no-unresolved-links) on project spring-cloud-docs: An Ant BuildException has occured: [Unresolved] Found...failing
[ERROR] around Ant part ...<fail message="[Unresolved] Found...failing">... @ 7:50 in /home/wwang/Git/spring-cloud-release/train-docs/target/antrun/build-main.xml
[ERROR] -> [Help 1]
[ERROR] 
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR] 
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException

Question

  1. Is something wrong with my operation?
  2. Cloud anybody give me a detail guidelines about how to build train-docs suucessfully?
  3. If you build successfully, could you please send me your build result to me via Email jackie-1685@163.com
  4. on official reference site, why does htmlsingle page not work?
ryanjbaxter commented 1 year ago

I followed the exact steps above and it build successfully

[INFO] Installing /Users/ryanjbaxter/temp/spring-cloud-release/train-docs/target/spring-cloud-docs-2021.0.5.jar to /Users/ryanjbaxter/.m2/repository/org/springframework/cloud/spring-cloud-docs/2021.0.5/spring-cloud-docs-2021.0.5.jar
[INFO] Installing /Users/ryanjbaxter/temp/spring-cloud-release/train-docs/.flattened-pom.xml to /Users/ryanjbaxter/.m2/repository/org/springframework/cloud/spring-cloud-docs/2021.0.5/spring-cloud-docs-2021.0.5.pom
[INFO] Installing /Users/ryanjbaxter/temp/spring-cloud-release/train-docs/target/spring-cloud-docs-2021.0.5-javadoc.jar to /Users/ryanjbaxter/.m2/repository/org/springframework/cloud/spring-cloud-docs/2021.0.5/spring-cloud-docs-2021.0.5-javadoc.jar
[INFO] Installing /Users/ryanjbaxter/temp/spring-cloud-release/train-docs/target/spring-cloud-docs-2021.0.5-sources.jar to /Users/ryanjbaxter/.m2/repository/org/springframework/cloud/spring-cloud-docs/2021.0.5/spring-cloud-docs-2021.0.5-sources.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  04:17 min
[INFO] Finished at: 2022-11-30T20:29:08-05:00
[INFO] ------------------------------------------------------------------------

Here are the single page docs https://docs.spring.io/spring-cloud/docs/current/reference/htmlsingle/spring-cloud.html

supermanHub commented 1 year ago

@ryanjbaxter , Hi Ryan, Thanks for your feedback.

I tried it again in a very clean environment(new virtual machine), but it still failed. I don't know why and do not have any idea to get succeed!

I re-access the https://docs.spring.io/spring-cloud/docs/current/reference/htmlsingle/spring-cloud.html again and found it has been update and can work well now. But before it looks like below(same as my build result): Screenshot from 2022-12-05 20-44-15

My Request

  1. how about upload your build result to Github, so that developers who can not successfully build train-docs can download it.
  2. If you or your team can not upload it to Github due to some policy reasons, then how about send your build result(train-docs) to me directly via email jackie-1685@163.com . Many thanks!
ryanjbaxter commented 1 year ago

I am not sure. You can download the HTML file from above for offline use if that is what you are trying to do

supermanHub commented 1 year ago

@ryanjbaxter Hi Ryan, good idea, thank you very much.