Add initial new website (see #2232) (#2513)

* Add initial new website (see #2232)

* Add mkdocs-minify-plugin to website generation

* Pinned versions in Pipfile

* Add mkdocs-git-revision-date-plugin to website generation

* Replace mkdocs-git-revision-date-plugin with mkdocs-git-revision-date-localized-plugin for website generation

.devcontainer/devcontainer.json

@@ -7,7 +7,8 @@
 
  "features": {
  // https://github.com/akhildevelops/devcontainer-features/issues/7
- "ghcr.io/akhildevelops/devcontainer-features/android-cli:0": {}
+ "ghcr.io/akhildevelops/devcontainer-features/android-cli:0": {},
+ "ghcr.io/devcontainers-contrib/features/pipenv:2": {}
 
  // https://github.com/CASL0/devcontainer-features/issues/4
  // "ghcr.io/casl0/devcontainer-features/android-sdk:1": {}

.github/workflows/build.yml

@@ -99,6 +99,16 @@ jobs:
  # This deploys content based on docs/ which ends up in site/
  # to https://google.github.io/android-fhir/ using GitHub Pages.
 
+ - name: Install Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: 3.11
+ cache: "pipenv"
+ - name: Install PipEnv
+ uses: tiagovrtr/actions-pipenv@v1
+ with:
+ pipenv-version: 2023.12.1
+
  - name: Build Docs Site
  # This 1st step intentionally runs not just on the main ("master") branch
  # but also for all pull requests. This serves to detect doc breakages.

.vscode/extensions.json

@@ -1,3 +1,7 @@
 {
- "recommendations": ["davidanson.vscode-markdownlint"]
+ "recommendations": [
+ "davidanson.vscode-markdownlint",
+ "streetsidesoftware.code-spell-checker",
+ "redhat.vscode-yaml"
+ ]
 }

.vscode/settings.json

@@ -0,0 +1,14 @@
+{
+ // https://squidfunk.github.io/mkdocs-material/creating-your-site/
+ "yaml.schemas": {
+ "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yaml"
+ },
+ "yaml.customTags": [
+ "!ENV scalar",
+ "!ENV sequence",
+ "!relative scalar",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
+ "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
+ "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
+ ]
+}

Pipfile

@@ -0,0 +1,14 @@
+[[source]]
+url = "https://pypi.org/simple"
+verify_ssl = true
+name = "pypi"
+
+[packages]
+mkdocs-material = "~=9.5.21"
+mkdocs-minify-plugin = "~=0.8.0"
+mkdocs-git-revision-date-localized-plugin = "~=1.2.5"
+
+[dev-packages]
+
+[requires]
+python_version = "3.11"

build-docs.bash

@@ -20,14 +20,15 @@ set -euox pipefail
 rm -rf site/
 mkdir -p site/
 
-# TODO https://github.com/google/android-fhir/issues/2232 Add mkdocs generation
+# "install --deploy" is better than "sync", because it checks that the Pipfile.lock
+# is up-to-date with the Pipfile before installing. If it's not, it will fail the
+# installation. This is useful for ensuring strict dependency control during CI.
+pipenv install --deploy
+pipenv run mkdocs build
 
 ./gradlew dokkaHtml
 mkdir -p site/api/
 mv docs/data-capture site/api/
 mv docs/engine site/api/
 mv docs/knowledge site/api/
 mv docs/workflow site/api/
-
-cp -R docs/index.html site/
-

docs/contrib/docs.md

@@ -0,0 +1,25 @@
+# Docs
+
+Developer Documentation for both users of and contributors to this project is maintained
+alongside its code in [the `docs/` folder its git repo](https://github.com/google/android-fhir/tree/master/docs).
+
+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.
+
+You can edit the `docs/**.md` files with any editor you like and include such changes with your regular Pull Requests.
+
+New MD files needs to be added to `nav:` in [`mkdocs.yaml`](https://github.com/google/android-fhir/blob/master/mkdocs.yaml).
+
+To generate the website, for simplicity we recommend using [GitHub Codespaces](codespaces.md); in a Terminal of such a Codespace:
+
+1. `pipenv shell`: This enters a [Python "virtual environment" (`venv`)](https://docs.python.org/3/library/venv.html), using [`pipenv`](https://pipenv.pypa.io/)
+
+1. `mkdocs serve`
+
+1. Confirm Codespace's _"Port Forward"_ prompt to open `https://...app.github.dev`, et voilà!
+

docs/index.md

@@ -0,0 +1,6 @@
+# Welcome to Android FHIR SDK Technical Documentation
+
+The Android FHIR SDK is a set of Kotlin libraries for building offline-capable, mobile-first
+healthcare applications using the [HL7® FHIR® standard](https://www.hl7.org/fhir/) on Android. It
+aims to accelerate the adoption of FHIR by making it easy to incorporate FHIR into new and existing
+mobile applications.

docs/use/api.md

@@ -0,0 +1,6 @@
+# API
+
+* [Engine](/api/engine/1.0.0/)
+* [Data Capture](/data-capture/1.1.0/)
+* [Workflow](/api/workflow/0.1.0-alpha04/)
+* [Knowledge](/api/knowledge/0.1.0-alpha03/)

mkdocs.yaml

@@ -0,0 +1,38 @@
+site_name: Android FHIR SDK
+site_url: https://google.github.io/android-fhir/
+repo_url: https://github.com/google/android-fhir/
+edit_uri: blob/master/docs/
+copyright: Copyright 2024 The Android FHIR SDK Authors
+
+nav:
+ - Users:
+ - API: use/api.md
+ - Contributors:
+ - Codespaces: contrib/codespaces.md
+ - Documentation: contrib/docs.md
+
+# The following settings were originally partially inspired by
+# https://github.com/enola-dev/enola/blob/main/mkdocs.yaml
+
+theme:
+ name: material
+ features:
+ - content.action.edit
+ - content.code.copy
+ - navigation.expand
+ - navigation.footer
+ - navigation.instant
+ - navigation.tracking
+ - navigation.expand
+ - navigation.path
+ - navigation.top
+ - navigation.sections
+ - navigation.tabs
+ - search.suggest
+ - search.share
+
+plugins:
+ - search
+ - git-revision-date-localized
+ - minify:
+ minify_html: true