Skip to content

Docs

Developer Documentation for both users of and contributors to this project is maintained alongside its code in the docs/ folder its git repo.

The https://google.github.io/android-fhir/ website is automatically generated from this with Continous Integration.

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.

To generate the website, for simplicity we recommend using GitHub Codespaces; in a Terminal of such a Codespace:

  1. pipenv shell: This enters a Python "virtual environment" (venv), using pipenv

  2. pipenv install: This install the required tools listed in the Pipfile

  3. mkdocs serve

  4. Confirm Codespace's "Port Forward" prompt to open https://...app.github.dev, et voilà!

Implementation Details

The website is built using Material for MkDocs.

The GitHub Action Build (defined in build.yml) runs the 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.)

The publication works by using the 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 action to actually publish that artifact to the live website.