diff --git a/README.adoc b/README.adoc index 864bcdf1..7c902be1 100644 --- a/README.adoc +++ b/README.adoc @@ -19,6 +19,7 @@ image:https://github.com/aim42/htmlSanityCheck/actions/workflows/gradle-build.ym image:https://sonarcloud.io/api/project_badges/measure?project=aim42_htmlSanityCheck&metric=alert_status[alt='Quality Gate Status'] image:https://jitpack.io/v/org.aim42.htmlSanityCheck/htmlSanityCheck.svg[alt='JitPack Build'] image:https://img.shields.io/github/issues/aim42/htmlSanityCheck.svg[link="https://github.com/aim42/htmlSanityCheck/issues"] +image:https://api.netlify.com/api/v1/badges/eea7288d-13ca-4268-b08d-f22e51173734/deploy-status[alt="Netlify Status",link=https://hsc-aim42.netlify.app/] [[sec:usage,usage]] diff --git a/src/docs/development/documentation-build.adoc b/src/docs/development/documentation-build.adoc index 163a3fa6..ea490f15 100644 --- a/src/docs/development/documentation-build.adoc +++ b/src/docs/development/documentation-build.adoc @@ -1,5 +1,5 @@ :filename: development/documentation-build.adoc -:jbake-title: Documentation Build +:jbake-title: Building and Publishing HSC Documentation :jbake-type: page :jbake-status: published :jbake-menu: development @@ -9,6 +9,8 @@ The documentation is maintained using the awesome https://github.com/docToolchain/docToolchain[docToolchain], created by https://rdmueller.github.io/[@rdmueller]. +=== Local Documentation Build + Build the complete documentation by executing the following build script: [source,bash] @@ -22,4 +24,27 @@ Afterwards, open // :doc-base: ../../../public ifdef::jbake-type[:doc-base: ..] * xref:{doc-base}/index.adoc[`public/index.html`] to check the results, or -* The xref:{doc-base}/report/report.adoc[HSC report] to check the quality. +* The xref:{doc-base}/report/report.adoc[HSC report] (`public/report/report.html`) to check the quality. + +=== Publishing the Documentation + +A https://github.com/aim42/htmlSanityCheck/actions/workflows/gh-pages.yml[GitHub Action] builds the documentation on each push (or pull request). + +Default:: +For each branch, +the GH action publishes the resulting documentation to https://www.netlify.com/[Netlify] +(check the output of the GH Action for the URL). + +Production:: +To publish to https://aim42.github.io/htmlSanityCheck[GitHub Pages], +you have to manually execute the https://github.com/aim42/htmlSanityCheck/actions/workflows/gh-pages.yml[GitHub Action] +and check the box to publish to GH Pages: ++ +image::gh-pages-action-publish-screenshot.png[] ++ +[CAUTION] +==== +In the future we might restrict publishing to particular branches +to ensure the documentation aligns with certain states of development, +e.g., `main` branch only. +==== \ No newline at end of file diff --git a/src/docs/images/gh-pages-action-publish-screenshot.png b/src/docs/images/gh-pages-action-publish-screenshot.png new file mode 100644 index 00000000..9092681e Binary files /dev/null and b/src/docs/images/gh-pages-action-publish-screenshot.png differ