Introduce preview of documentation changes for PRs

[rsvoboda]

Description

Quarkus documentation is getting bigger, there are already includes present. Further modularization of common parts is a natural thing to happen. And thus it would be good to have a preview of rendered documentation changes as part of PR when the content in the docs directory is updated.

quarkusio.github.io repository uses preview functionality in PRs already and similar approach could be applied to the main repository for docs changes.

Implementation ideas

One option can be to use https://pypi.org/project/html-diff/ library

pip install html-diff ~/Library/Python/3.9/bin/htmldiff - on macOS (in my case) ~/.local/bin/htmldiff - on Linux

Examples of removals and additions:

• designed in a way that <del>it looks quite similar to writing a GraphQL query as a string.</del></td>
• representing <ins>Added something denting</ins> the GraphQL query, using the provided DSL language.

Idea for docs compare:

# assuming generated-docs-upstream and generated-docs-pr directories for comparison

for DOCS_FILE in `ls generated-docs-upstream | grep html`; do 
  ~/Library/Python/3.9/bin/htmldiff -o diff.html -l ERROR generated-docs-upstream/${DOCS_FILE} generated-docs-pr/${DOCS_FILE}
  CHANGED_LINES=`grep -e '<del>' -e '<ins>' diff.html | wc -l`
  echo "${CHANGED_LINES}  ...  ${DOCS_FILE}"; 
  if [ "${CHANGED_LINES}" -gt "0" ]; then
     echo "                  .... archiving file into folder ABC"
  fi 
done
echo "                  .... publishing folder ABC"

Exec time of the for cycle is ~ 5 minutes, all-config guide takes some time

Static web publishing options:

• https://surge.sh/
• https://github.com/afc163/surge-preview
• https://geekflare.com/best-static-site-hosting-platform/

CC @ebullient, @inoxx03 @gastaldi may give some insight as I think he worked on surge for quarkusio.github.io

@MichalMaler, @sheilamjones, @mjurc fyi

[quarkus-bot[bot]]

/cc @MichalMaler, @ebullient, @hmanwani-rh, @inoxx03, @michelle-purcell, @sheilamjones, @sunayna15

[ebullient]

This will have to wait for a little bit (we may get there). Any of the above changes listed will already be in the upstream PR, granted, in a raw format. Nightly sync puts any changes that have been merged... our PR changes (upstream) are generally finer grained, so the wording changes that you provided as an example above would be in tinier diffs in different PRs.

I guess my question is: what is the actual granularity of changes you want to see? Minor upstream changes, or the accumulation of changes in a version branch? or...

[gsmet]

Done recently.