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

convert changelog and generate documentation in markdown format. #1161

Merged
merged 11 commits into from
Jun 16, 2022

Conversation

zhumin8
Copy link
Contributor

@zhumin8 zhumin8 commented Jun 7, 2022

[updated.]

  • removed old CHANGELOG.adoc and replaced with CHANGELOG.md.
  • in prep for markdown generation, added first-page.adoc and configuration.adoc (sections copied from index.adoc) so that result full doc can be concatenation of docs.
  • produced doc per module to markdown to folder docs/src/main/md/
  • in spring-cloud-bus-pubsub.md, replaced spring_cloud_bus_over_pubsub.png with link to github.

Used asciidoctor and pandoc to convert asciidoc to markdown.
Steps to generate the markdown files:

# convert changelog to md
sudo asciidoctor -b docbook CHANGELOG.adoc   
sudo pandoc -f docbook -t gfm CHANGELOG.xml -o CHANGELOG.md --shift-heading-level-by=1


# convert doc to md
cd docs/src/main/md
./convert-from-ascii.sh  

# manual copy title over from index.adoc (due to pandoc settings, this title is not carried over.)

@zhumin8 zhumin8 marked this pull request as ready for review June 9, 2022 17:13
@zhumin8 zhumin8 requested a review from elefeint June 9, 2022 17:13
Copy link
Contributor

@elefeint elefeint left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, but I think we are going to find it harder to maintain the one single reference documentation file.

Is there any way to have individual per-product files that get combined into a single file with some pre/post processing when publishing?

docs/src/main/md/index.md Outdated Show resolved Hide resolved
docs/src/main/md/index.md Outdated Show resolved Hide resolved
docs/src/main/md/index.md Outdated Show resolved Hide resolved
docs/src/main/md/index.md Outdated Show resolved Hide resolved
docs/src/main/md/index.md Outdated Show resolved Hide resolved
@zhumin8
Copy link
Contributor Author

zhumin8 commented Jun 10, 2022

this pr is rebased after #1164 merged in so that title level issues are addressed.
Based on the idea to have individual per-product files, revamped this pr to adding separate markdown docs. and leaving the concatenation of them as step in publishing (will be in.kokoro/publish_javadoc11.sh on #1167 ).
Also updated pr description above to reflect latest changes.

@zhumin8 zhumin8 requested a review from elefeint June 10, 2022 22:53
@sonarqubecloud
Copy link

Kudos, SonarCloud Quality Gate passed!    Quality Gate passed

Bug A 0 Bugs
Vulnerability A 0 Vulnerabilities
Security Hotspot A 0 Security Hotspots
Code Smell A 0 Code Smells

No Coverage information No Coverage information
No Duplication information No Duplication information

Copy link
Contributor

@elefeint elefeint left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks great.
If the two spring integration documentation parts (pub/sub and storage) become unwieldy in the future, we can split them up then.

@zhumin8 zhumin8 merged commit 50a1db3 into main Jun 16, 2022
@zhumin8 zhumin8 deleted the adding-md branch June 16, 2022 12:58
kateryna216 added a commit to kateryna216/spring-cloud-gcp that referenced this pull request Oct 20, 2022
…gleCloudPlatform#1161)

* change CHANGELOG from asciidoc to markdown file.

* produce documentation in markdown in separate folder.

* remove image as it does not go through the pipeline. edit image path in doc.

* replace spring_cloud_bus_over_pubsub image with link.

* adding files to convert and assemble markdownfiles for each module.

* remove all-in-one markdown doc.

* fix list of file to convert and to include in doc.

* adding md files per module.

* copy title over to first-page.md

* replace spring_cloud_bus_over_pubsub image with link.

* remove yaml file to use with pandoc --defaults. use older syntax in script instead.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants