Merge pull request #6 from LinuxForHealth/doc_updates

Doc updates

Author: ntl-ibm

.github/workflows/build-docs.yml

@@ -0,0 +1,36 @@
+# This runs when either mkdocs.yml or anything in the docs directory 
+# is changed, and the change is pushed to main.
+#
+# It will deploy the rendered HTML to a gh-pages branch.
+#
+# GitHub should be setup to use this branch's root dir as a source
+# for gh-pages. When changes are pushed to the branch, a GitHub action
+# will publish the changes to the pages environment.
+#
+# The gh-pages branch should never be modified, except by this action.
+# Part of the deploy is deleting existing files.
+name: Documentation
+
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+  workflow_dispatch:
+  
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v2
+      - run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
+      - run: git config user.name ${{ github.actor }} && git config user.email "${{ github.actor }}@users.noreply.github.com"
+      - name: Publish docs
+        run: mkdocs gh-deploy
+

.github/workflows/nlp-insights-push-validation.yml

@@ -1,8 +1,14 @@
+# This does a Build, Test, Validate on ever push to a user branch
+# The idea is that testcase and source code problems are reported 
+# early...before a pull request.
+#
 name: nlp-insights PUSH Validation
 on: 
   push:
    branches-ignore:
     - 'main'
+   paths-ignore:
+    - 'docs/**.md'
 defaults:
   run:
     shell: bash

.github/workflows/prepare-doc-release.yml

@@ -0,0 +1,44 @@
+# This workflow performs markdown processing as part of prepare release
+# It only runs if markdown files are changed.
+#
+# This uses the same name and job name as prepare-release.yml.
+# There is a branch protection status check that requires a workflow
+# with this name to pass. Since thes both only run under certain conditions,
+# they both have to share the same name so that at least one of them runs.
+#
+# Othewise the pull can never be merged because no status check runs.
+# This is described here: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks#handling-skipped-but-required-checks
+name: Prepare to release nlp-insights 
+on:
+  pull_request:
+    types: [opened, synchronize, labeled, reopened]
+    branches:
+      - main
+    paths:
+      - 'docs/**.md'
+
+jobs:
+  prepare-release:
+    # Don't change this Name, must match prepare-release.yml and a status check
+    name: Prepare release
+    runs-on: ubuntu-latest
+
+    steps:
+
+      - uses: actions/checkout@v2
+        with:
+          fetch-depth: 0
+      - name: Checkout branch
+        run: |
+             git fetch
+             git checkout ${{ github.event.pull_request.head.ref }}
+
+      - name: Validate Documentation
+        run: |
+             pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
+             mkdocs build -s
+
+      - name: noop 
+        run: echo "No docker build for doc changes"
+
+

.github/workflows/prepare-release.yml

@@ -1,12 +1,26 @@
+# This workflow performs the container image build as part of prepare release
+# It runs if any files other than markdown files are changed.
+#
+# This uses the same name and job name as prepare-doc-release.yml.
+# There is a branch protection status check that requires a workflow
+# with this name to pass. Since thes both only run under certain conditions,
+# they both have to share the same name so that at least one of them runs.
+#
+# Othewise the pull can never be merged because no status check runs.
+# This is described here: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/troubleshooting-required-status-checks#handling-skipped-but-required-checks
 name: Prepare to release nlp-insights 
 on:
   pull_request:
     types: [opened, synchronize, labeled, reopened]
     branches:
       - main
+    paths-ignore:
+      - 'docs/**.md'
 
 jobs:
   prepare-release:
+    # Don't change this name, must match prepare-doc-release.yml,
+    # must match status check name
     name: Prepare release
     runs-on: ubuntu-latest
 
@@ -68,7 +82,14 @@ jobs:
 
       - name: Docker Lint
         run:  dockerlint
-
+      # We don't want to continue this build and indicate success if something
+      # is wrong with the docs. This is usually a quick operation so doing it
+      # even if no documentation changed is not a problem, we'll always publish the
+      # docs, because that is where the charts get archived.
+      - name: Validate Documentation
+        run: |
+             pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
+             mkdocs build -s      
       - name: Push Docker Image
         run: |
              ./gradlew dockerPush -PdockerUser=${{ env.docker_server }}/${{ env.docker_org }}

.github/workflows/release.yml

@@ -1,3 +1,14 @@
+# This adds the release tag on pushes to main
+# iff the release defined by gradle.properties 
+# does not already have a tag.
+# A Case where a new release would not be created might be a doc only update.
+#
+# Releases are created as pre-releases, which tells consumers that
+# the release isn't ready for production (or general use in our case).
+# To make the release "official", go the the repo on the web:
+#  - choose Releases (from the right nav bar), 
+#  - Edit the release
+#  - Uncheck "This is a pre-release"
 name: Add a release tag for nlp-insights 
 on:
   push:
@@ -15,7 +26,10 @@ jobs:
           fetch-depth: 0
       - name: Calculate Tag
         run:  echo "TAG=v$(grep -oP 'version\=\K([0-9]+\.[0-9]+\.[0-9]+)' gradle.properties)" >> $GITHUB_ENV
+      - name: Check if the release already exists
+        run:  echo "EXISTS=$(wget -q https://api.github.com/repos/ntl-ibm/nlp-insights/releases -O - | jq 'any(.[].tag_name == env.TAG; .)')" >> $GITHUB_ENV
       - name: Create Release
+        if: ${{ env.EXISTS != 'true' }}
         uses: actions/create-release@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -2,3 +2,8 @@ build
 .gradle
 .project
 .pydevproject
+__pycache__/
+docs/**/.*.md.html
+/.mypy_cache/
+site
+**/*.swp

README.md

@@ -1,5 +1,5 @@
 # NLP Insights
-A Rest service for updating bundles of FHIR resources with discovered insights.
+A reference implementation of a rest service to update bundles of FHIR resources with discovered insights.
 The service is implemented as a Flask API within a docker container.
 
 ## Purpose
@@ -9,47 +9,28 @@ The primary purpose of the discover insights API is to accept a bundle of FHIR r
 * New resources may have been derived from unstructured text (such as clinical notes) contained within the bundle's resources. 
   - For example a DiagnosticReport that says *the patient had a myocardial infarction* might result in a derived Condition resource being added to the bundle.
 
-
-## Supported NLP Engines
-The nlp-insights service requires an NLP engine service to perform NLP related tasks. We support two NLP services.
-
-* IBM's [Annotator for Clinical Data (ACD)](https://www.ibm.com/cloud/watson-annotator-for-clinical-data) and 
-* Open-source [QuickUMLS](https://github.com/Georgetown-IR-Lab/QuickUMLS)
-
-
 ## Quick Start
-Our tutorials describe how to setup and configure nlp-insights with a supported NLP service. They also provide extensive description of how resources are derived and enriched:
-
-* [Tutorial for using the nlp-insights service with QuickUMLS](./docs/examples/quickumls/quickumls_tutorial.md)
-* [Tutorial for using the nlp-insights service with ACD](./docs/examples/acd/acd_tutorial.md)
-
-
-## Running the service locally
-The docker image for the container has been published, and you can pull it from [here](https://hub.docker.com/r/alvearie/nlp-insights).
-
-Developers that have cloned the repo should follow the instructions for starting the service that are documented [here](./docs/examples/setup/start_nlp_insights.md).
+You can pull the latest release from quay.io. 
 
-Although discouraged, it is possible to [run the service outside of a docker container](./docs/developer/run_service_no_docker.md).
+The tag of the container image is always associated with the release tag for the git repo.
+In other words, to run the service for release v0.0.6 on local port 8998, you could execute:
 
-## Kubernetes
-The nlp-insights service is designed to be part of a larger health-patterns ingestion and enrichment pipeline. Helm charts are included so that the service can be deployed to kubernetes. The deployed service can then be integrated into a pipeline.
+```
+docker login quay.io
+docker run -p 8998:5000 quay.io/alvearie/nlp-insights:0.0.6
+```
 
-More details on deployment and configuration in a k8s environment are discussed [here](./docs/developer/kubernetes.md)
+The container's tag does not include a leading "v". The available tags can be accessed [here](https://quay.io/repository/alvearie/nlp-insights?tab=tags). We recommend loading images with tags that are associated with tagged releases in GitHub.
 
-## HTTP Endpoints
-The HTTP APIs for the service are described [here](./docs/developer/http_endpoints.md).
-These APIs allow you to:
+Example use cases, APIs, and buid documentation can be found in our official product [documentation](#documentation).
 
-* Define the connection to the NLP engine service(s),
-* Select the default NLP engine that will be used for insight discovery
-* Discover insights
-* Override the default engine and use a different NLP engine for one or more resource types
+It's also very easy to build the container from source code, and the directions to do that can be found in the documentation.
 
-## Build
-We use gradle for all build and test related tasks. The important features are documented [here](./docs/developer/gradle_tasks.md).
+## Documentation
+The official documentation is located [here](https://linuxforhealth.github.io/nlp-insights)
 
 ## Contributing
-We welcome contributions! Please look at our [contributing guide](./docs/developer/CONTRIBUTING.md) for details on how to begin.
+We welcome contributions! Please look at our [documentation](#documentation) for details on how to begin.
 
 
 ## License

chart/Chart.yaml

@@ -15,12 +15,12 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.1.2
+version: 0.1.3
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to
 # follow Semantic Versioning. They should reflect the version the application is using.
-appVersion: 0.1.2
+appVersion: 0.1.3
 
 keywords:
   - ibm

chart/values.yaml

@@ -7,7 +7,7 @@ replicaCount: 1
 image:
   repository: alvearie/nlp-insights
   pullPolicy: Always
-  tag: 0.1.2
+  tag: 0.1.3
   pullSecret:
 
 service:

docs/.gitignore

@@ -0,0 +1,6 @@
+_site
+.sass-cache
+.jekyll-cache
+.jekyll-metadata
+.*.md.html
+vendor

docs/_config.yml

@@ -0,0 +1,8 @@
+# Chart packages
+
+This directory contains chart information that 
+was packaged and published by the CI pipeline.
+
+It is not used by documentation, but is published with 
+the documentation. It is used by consumers to pull the
+helm charts for the service.

docs/charts/README.txt

@@ -1,9 +1,28 @@
 apiVersion: v1
 entries:
   nlp-insights:
+  - apiVersion: v2
+    appVersion: 0.1.3
+    created: "2022-03-09T20:39:30.438685533Z"
+    description: A Helm Chart to deploy the NLP Insights service.
+    digest: 286099b95180065ebe50b78cf2f5daa8d2d76a4fa51f46ad16e834332db9e902
+    home: https://github.com/LinuxForHealth/nlp-insights
+    keywords:
+    - ibm
+    - alvearie
+    - nlp
+    - insights
+    maintainers:
+    - email: [email protected]
+      name: Nicholas T. Lawrence
+    name: nlp-insights
+    type: application
+    urls:
+    - nlp-insights-0.1.3.tgz
+    version: 0.1.3
   - apiVersion: v2
     appVersion: 0.1.2
-    created: "2022-02-28T20:40:04.640360631Z"
+    created: "2022-03-09T20:39:30.437815031Z"
     description: A Helm Chart to deploy the NLP Insights service.
     digest: 42bed86de1f193821ca0a58269a44bdfa575d258be5b1b3950d0c64d9d5aa25a
     home: https://github.com/LinuxForHealth/nlp-insights
@@ -22,7 +41,7 @@ entries:
     version: 0.1.2
   - apiVersion: v2
     appVersion: 0.0.1
-    created: "2022-02-28T20:40:04.639759512Z"
+    created: "2022-03-09T20:39:30.437242729Z"
     description: A Helm Chart to deploy the NLP Insights service.
     digest: 0f23831266fa1c80fe75cc2cd8b35bb9325d047ac6470843d8624568ba73f7c7
     home: https://github.com/Alvearie/health-patterns/tree/main/services/nlp-insights
@@ -39,4 +58,4 @@ entries:
     urls:
     - nlp-insights-0.1.0.tgz
     version: 0.1.0
-generated: "2022-02-28T20:40:04.638926185Z"
+generated: "2022-03-09T20:39:30.435180423Z"

docs/charts/index.yaml

@@ -0,0 +1,15 @@
+.wy-nav-content {
+    max-width: 95% !important;
+}
+
+table {
+    width:95%;
+}
+
+.wy-table-responsive table td {
+    white-space: normal !important;
+}
+.wy-table-responsive {
+    overflow: visible !important;
+}
+