Add more documentation with technical details about how the new websi…

…te is generated (#2611) * Add more documentation with technical details about how the new website is generated * Update docs/contrib/docs.md Co-authored-by: Jing Tang <[email protected]> * Update docs/contrib/docs.md Co-authored-by: Jing Tang <[email protected]> * Update docs.md --------- Co-authored-by: Jing Tang <[email protected]>
google · Jul 10, 2024 · 88b5cd6 · 88b5cd6
1 parent 1d2da89
commit 88b5cd6
Showing 1 changed file with 12 additions and 2 deletions.
diff --git a/docs/contrib/docs.md b/docs/contrib/docs.md
@@ -5,8 +5,6 @@ alongside its code in [the `docs/` folder its git repo](https://github.com/googl
 
 The <https://google.github.io/android-fhir/> website is automatically generated from this with Continous Integration.
 
-This website is built using [Material](https://squidfunk.github.io/mkdocs-material/) for [MkDocs](https://www.mkdocs.org/).
-
 ## Contribute
 
 Contributions to the documentation are very welcome, and should typically be made together with code contributions.
@@ -23,3 +21,15 @@ To generate the website, for simplicity we recommend using [GitHub Codespaces](c
 
 1. Confirm Codespace's _"Port Forward"_ prompt to open `https://...app.github.dev`, et voilà!
 
+## Implementation Details
+
+The website is built using [Material](https://squidfunk.github.io/mkdocs-material/) for [MkDocs](https://www.mkdocs.org/).
+
+The GitHub Action [`Build`](https://github.com/google/android-fhir/actions/workflows/build.yml) (defined in [`build.yml`](https://github.com/google/android-fhir/blob/master/.github/workflows/build.yml)) runs the [`build-docs.bash`](https://github.com/google/android-fhir/blob/master/build-docs.bash) script to generate the HTML in the `site/` directory.
+That `site/` directory is created dynamically during the build process but never commited into the Git repository since it is included in the `.gitignore` file.
+
+The docs related build steps run for every PR, to help detect broken doc before merge. However, these runs do not update
+the live website, which only happens for builds of the `master` branch (notice `on: push: branches: [master]` and `if: ${{ github.event_name == 'push' }}` in [`build.yml`](https://github.com/google/android-fhir/blob/master/.github/workflows/build.yml).)
+
+The publication works by using the [`upload-pages-artifact`](https://github.com/actions/upload-pages-artifact) action to package the generated HTML from the `site/` directory,
+and uploading this artifact to a staging area on GitHub, and the [`deploy-pages`](https://github.com/actions/deploy-pages) action to actually publish that artifact to the live website.