Skip to content

Commit 4657dfd

Browse files
ntl-ibmntl-ibm
authored
Merge pull request #6 from LinuxForHealth/doc_updates
Doc updates
2 parents 1578bf3 + 5056cf4 commit 4657dfd

40 files changed

+3029
-1387
lines changed

‎.github/workflows/build-docs.yml

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# This runs when either mkdocs.yml or anything in the docs directory
2+
# is changed, and the change is pushed to main.
3+
#
4+
# It will deploy the rendered HTML to a gh-pages branch.
5+
#
6+
# GitHub should be setup to use this branch's root dir as a source
7+
# for gh-pages. When changes are pushed to the branch, a GitHub action
8+
# will publish the changes to the pages environment.
9+
#
10+
# The gh-pages branch should never be modified, except by this action.
11+
# Part of the deploy is deleting existing files.
12+
name: Documentation
13+
14+
15+
on:
16+
push:
17+
branches:
18+
- main
19+
paths:
20+
- "docs/**"
21+
- "mkdocs.yml"
22+
workflow_dispatch:
23+
24+
jobs:
25+
docs:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v2
29+
with:
30+
fetch-depth: 0
31+
- uses: actions/setup-python@v2
32+
- run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
33+
- run: git config user.name ${{ github.actor }} && git config user.email "${{ github.actor }}@users.noreply.github.com"
34+
- name: Publish docs
35+
run: mkdocs gh-deploy
36+

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

+6
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,14 @@
1+
# This does a Build, Test, Validate on ever push to a user branch
2+
# The idea is that testcase and source code problems are reported
3+
# early...before a pull request.
4+
#
15
name: nlp-insights PUSH Validation
26
on:
37
push:
48
branches-ignore:
59
- 'main'
10+
paths-ignore:
11+
- 'docs/**.md'
612
defaults:
713
run:
814
shell: bash

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

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# This workflow performs markdown processing as part of prepare release
2+
# It only runs if markdown files are changed.
3+
#
4+
# This uses the same name and job name as prepare-release.yml.
5+
# There is a branch protection status check that requires a workflow
6+
# with this name to pass. Since thes both only run under certain conditions,
7+
# they both have to share the same name so that at least one of them runs.
8+
#
9+
# Othewise the pull can never be merged because no status check runs.
10+
# 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
11+
name: Prepare to release nlp-insights
12+
on:
13+
pull_request:
14+
types: [opened, synchronize, labeled, reopened]
15+
branches:
16+
- main
17+
paths:
18+
- 'docs/**.md'
19+
20+
jobs:
21+
prepare-release:
22+
# Don't change this Name, must match prepare-release.yml and a status check
23+
name: Prepare release
24+
runs-on: ubuntu-latest
25+
26+
steps:
27+
28+
- uses: actions/checkout@v2
29+
with:
30+
fetch-depth: 0
31+
- name: Checkout branch
32+
run: |
33+
git fetch
34+
git checkout ${{ github.event.pull_request.head.ref }}
35+
36+
- name: Validate Documentation
37+
run: |
38+
pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
39+
mkdocs build -s
40+
41+
- name: noop
42+
run: echo "No docker build for doc changes"
43+
44+

‎.github/workflows/prepare-release.yml

+22-1
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,26 @@
1+
# This workflow performs the container image build as part of prepare release
2+
# It runs if any files other than markdown files are changed.
3+
#
4+
# This uses the same name and job name as prepare-doc-release.yml.
5+
# There is a branch protection status check that requires a workflow
6+
# with this name to pass. Since thes both only run under certain conditions,
7+
# they both have to share the same name so that at least one of them runs.
8+
#
9+
# Othewise the pull can never be merged because no status check runs.
10+
# 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
111
name: Prepare to release nlp-insights
212
on:
313
pull_request:
414
types: [opened, synchronize, labeled, reopened]
515
branches:
616
- main
17+
paths-ignore:
18+
- 'docs/**.md'
719

820
jobs:
921
prepare-release:
22+
# Don't change this name, must match prepare-doc-release.yml,
23+
# must match status check name
1024
name: Prepare release
1125
runs-on: ubuntu-latest
1226

@@ -68,7 +82,14 @@ jobs:
6882
6983
- name: Docker Lint
7084
run: dockerlint
71-
85+
# We don't want to continue this build and indicate success if something
86+
# is wrong with the docs. This is usually a quick operation so doing it
87+
# even if no documentation changed is not a problem, we'll always publish the
88+
# docs, because that is where the charts get archived.
89+
- name: Validate Documentation
90+
run: |
91+
pip install --upgrade pip && pip install mkdocs mkdocs-gen-files pymdown-extensions
92+
mkdocs build -s
7293
- name: Push Docker Image
7394
run: |
7495
./gradlew dockerPush -PdockerUser=${{ env.docker_server }}/${{ env.docker_org }}

‎.github/workflows/release.yml

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

‎.gitignore

+5
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,8 @@ build
22
.gradle
33
.project
44
.pydevproject
5+
__pycache__/
6+
docs/**/.*.md.html
7+
/.mypy_cache/
8+
site
9+
**/*.swp

‎README.md

+14-33
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
# NLP Insights
2-
A Rest service for updating bundles of FHIR resources with discovered insights.
2+
A reference implementation of a rest service to update bundles of FHIR resources with discovered insights.
33
The service is implemented as a Flask API within a docker container.
44

55
## Purpose
@@ -9,47 +9,28 @@ The primary purpose of the discover insights API is to accept a bundle of FHIR r
99
* New resources may have been derived from unstructured text (such as clinical notes) contained within the bundle's resources.
1010
- For example a DiagnosticReport that says *the patient had a myocardial infarction* might result in a derived Condition resource being added to the bundle.
1111

12-
13-
## Supported NLP Engines
14-
The nlp-insights service requires an NLP engine service to perform NLP related tasks. We support two NLP services.
15-
16-
* IBM's [Annotator for Clinical Data (ACD)](https://www.ibm.com/cloud/watson-annotator-for-clinical-data) and
17-
* Open-source [QuickUMLS](https://github.com/Georgetown-IR-Lab/QuickUMLS)
18-
19-
2012
## Quick Start
21-
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:
22-
23-
* [Tutorial for using the nlp-insights service with QuickUMLS](./docs/examples/quickumls/quickumls_tutorial.md)
24-
* [Tutorial for using the nlp-insights service with ACD](./docs/examples/acd/acd_tutorial.md)
25-
26-
27-
## Running the service locally
28-
The docker image for the container has been published, and you can pull it from [here](https://hub.docker.com/r/alvearie/nlp-insights).
29-
30-
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).
13+
You can pull the latest release from quay.io.
3114

32-
Although discouraged, it is possible to [run the service outside of a docker container](./docs/developer/run_service_no_docker.md).
15+
The tag of the container image is always associated with the release tag for the git repo.
16+
In other words, to run the service for release v0.0.6 on local port 8998, you could execute:
3317

34-
## Kubernetes
35-
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.
18+
```
19+
docker login quay.io
20+
docker run -p 8998:5000 quay.io/alvearie/nlp-insights:0.0.6
21+
```
3622

37-
More details on deployment and configuration in a k8s environment are discussed [here](./docs/developer/kubernetes.md)
23+
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.
3824

39-
## HTTP Endpoints
40-
The HTTP APIs for the service are described [here](./docs/developer/http_endpoints.md).
41-
These APIs allow you to:
25+
Example use cases, APIs, and buid documentation can be found in our official product [documentation](#documentation).
4226

43-
* Define the connection to the NLP engine service(s),
44-
* Select the default NLP engine that will be used for insight discovery
45-
* Discover insights
46-
* Override the default engine and use a different NLP engine for one or more resource types
27+
It's also very easy to build the container from source code, and the directions to do that can be found in the documentation.
4728

48-
## Build
49-
We use gradle for all build and test related tasks. The important features are documented [here](./docs/developer/gradle_tasks.md).
29+
## Documentation
30+
The official documentation is located [here](https://linuxforhealth.github.io/nlp-insights)
5031

5132
## Contributing
52-
We welcome contributions! Please look at our [contributing guide](./docs/developer/CONTRIBUTING.md) for details on how to begin.
33+
We welcome contributions! Please look at our [documentation](#documentation) for details on how to begin.
5334

5435

5536
## License

‎chart/Chart.yaml

+2-2
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ type: application
1515
# This is the chart version. This version number should be incremented each time you make changes
1616
# to the chart and its templates, including the app version.
1717
# Versions are expected to follow Semantic Versioning (https://semver.org/)
18-
version: 0.1.2
18+
version: 0.1.3
1919

2020
# This is the version number of the application being deployed. This version number should be
2121
# incremented each time you make changes to the application. Versions are not expected to
2222
# follow Semantic Versioning. They should reflect the version the application is using.
23-
appVersion: 0.1.2
23+
appVersion: 0.1.3
2424

2525
keywords:
2626
- ibm

‎chart/values.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ replicaCount: 1
77
image:
88
repository: alvearie/nlp-insights
99
pullPolicy: Always
10-
tag: 0.1.2
10+
tag: 0.1.3
1111
pullSecret:
1212

1313
service:

‎docs/.gitignore

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
_site
2+
.sass-cache
3+
.jekyll-cache
4+
.jekyll-metadata
5+
.*.md.html
6+
vendor

‎docs/_config.yml

-1
This file was deleted.

‎docs/charts/README.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Chart packages
2+
3+
This directory contains chart information that
4+
was packaged and published by the CI pipeline.
5+
6+
It is not used by documentation, but is published with
7+
the documentation. It is used by consumers to pull the
8+
helm charts for the service.

‎docs/charts/index.yaml

+22-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,28 @@
11
apiVersion: v1
22
entries:
33
nlp-insights:
4+
- apiVersion: v2
5+
appVersion: 0.1.3
6+
created: "2022-03-09T20:39:30.438685533Z"
7+
description: A Helm Chart to deploy the NLP Insights service.
8+
digest: 286099b95180065ebe50b78cf2f5daa8d2d76a4fa51f46ad16e834332db9e902
9+
home: https://github.com/LinuxForHealth/nlp-insights
10+
keywords:
11+
- ibm
12+
- alvearie
13+
- nlp
14+
- insights
15+
maintainers:
16+
- email: [email protected]
17+
name: Nicholas T. Lawrence
18+
name: nlp-insights
19+
type: application
20+
urls:
21+
- nlp-insights-0.1.3.tgz
22+
version: 0.1.3
423
- apiVersion: v2
524
appVersion: 0.1.2
6-
created: "2022-02-28T20:40:04.640360631Z"
25+
created: "2022-03-09T20:39:30.437815031Z"
726
description: A Helm Chart to deploy the NLP Insights service.
827
digest: 42bed86de1f193821ca0a58269a44bdfa575d258be5b1b3950d0c64d9d5aa25a
928
home: https://github.com/LinuxForHealth/nlp-insights
@@ -22,7 +41,7 @@ entries:
2241
version: 0.1.2
2342
- apiVersion: v2
2443
appVersion: 0.0.1
25-
created: "2022-02-28T20:40:04.639759512Z"
44+
created: "2022-03-09T20:39:30.437242729Z"
2645
description: A Helm Chart to deploy the NLP Insights service.
2746
digest: 0f23831266fa1c80fe75cc2cd8b35bb9325d047ac6470843d8624568ba73f7c7
2847
home: https://github.com/Alvearie/health-patterns/tree/main/services/nlp-insights
@@ -39,4 +58,4 @@ entries:
3958
urls:
4059
- nlp-insights-0.1.0.tgz
4160
version: 0.1.0
42-
generated: "2022-02-28T20:40:04.638926185Z"
61+
generated: "2022-03-09T20:39:30.435180423Z"

‎docs/charts/nlp-insights-0.1.3.tgz

2.75 KB
Binary file not shown.

‎docs/css/extra.css

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.wy-nav-content {
2+
max-width: 95% !important;
3+
}
4+
5+
table {
6+
width:95%;
7+
}
8+
9+
.wy-table-responsive table td {
10+
white-space: normal !important;
11+
}
12+
.wy-table-responsive {
13+
overflow: visible !important;
14+
}
15+

0 commit comments

Comments
 (0)