Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update the READMEs and init mkDocs (DSP-1298) #271

Merged
merged 46 commits into from Feb 2, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
46 commits
Select commit Hold shift + click to select a range
e979c77
docs: add mkDocs
kilchenmann Jan 28, 2021
a3cd7ae
docs: copy from dsp-docs
kilchenmann Jan 28, 2021
5265164
docs(contribution): mv contribution file to mkdocs
kilchenmann Jan 29, 2021
23f2813
docs(contribution): mv design docs to mkdocs
kilchenmann Jan 29, 2021
82b3000
docs(structure): refactor file structure and content
kilchenmann Jan 29, 2021
af36970
docs(gh-ci): build and deploy docs
kilchenmann Jan 29, 2021
4c3cf08
Merge branch 'main' into wip/dsp-1298-update-docs
Jan 29, 2021
e1fb67d
docs(gh-ci): bug fix in workflow
kilchenmann Jan 29, 2021
febc31a
Merge branch 'wip/dsp-1298-update-docs' of https://github.com/dasch-s…
kilchenmann Jan 29, 2021
f837fca
docs(structure): refactor file structure and content
kilchenmann Jan 29, 2021
2d19043
docs: set index
kilchenmann Jan 29, 2021
9036608
docs: update main README
kilchenmann Jan 29, 2021
1a381d0
docs(mkdocs): Update config
kilchenmann Jan 29, 2021
06adf6f
docs: update mkdocs README
kilchenmann Jan 29, 2021
8b4c254
chore: update build-lib process
kilchenmann Jan 29, 2021
fc244b1
docs: clean up and refactor
kilchenmann Jan 29, 2021
4072f5a
docs: restructure file structure
kilchenmann Jan 30, 2021
fc5bacd
docs(style): update theme
kilchenmann Jan 30, 2021
49f9f71
docs: move lib's README to documentation
kilchenmann Jan 30, 2021
ab709fe
docs(config): update mkdocs conf
kilchenmann Jan 30, 2021
dfd26a5
docs: update README
kilchenmann Jan 30, 2021
c20139b
docs(config): add revision date plugin
kilchenmann Jan 30, 2021
9bf7750
docs: update mkdocs README
kilchenmann Jan 30, 2021
c909031
docs(contribution): add mkdocs documentation
kilchenmann Jan 30, 2021
4a56552
docs: refactor old content
kilchenmann Jan 30, 2021
6021310
chore(gh-ci): activate docs deployment once
kilchenmann Jan 30, 2021
bfa1ef6
docs(mkdocs): updata mkdocs README
kilchenmann Jan 30, 2021
b16f7d5
docs(gh-ci): add mkdocs plugins to deploy docs
kilchenmann Jan 30, 2021
6397125
chore(gh-ci): fix docs deployment
kilchenmann Jan 30, 2021
487cd84
chore(gh-ci): fix docs deployment
kilchenmann Jan 30, 2021
7deead3
chore(gh-ci): deploy docs on release only
kilchenmann Jan 30, 2021
9dc2c7e
docs(contribution): update release process
kilchenmann Jan 30, 2021
5b2802a
chore(gh-ci): better title
kilchenmann Jan 30, 2021
a4684a4
docs(README): update dead links
kilchenmann Jan 30, 2021
d6c446c
docs(config): update copyright info
kilchenmann Jan 30, 2021
1d92cce
chore(gh-ci): deploy docs once again
kilchenmann Jan 30, 2021
14abcad
chore(gh-ci): run docs deployment on release only
kilchenmann Jan 30, 2021
f10c104
docs(mkdocs): update README
kilchenmann Feb 2, 2021
f8f1fcd
docs: consistent use of the term dsp-ui
kilchenmann Feb 2, 2021
455427d
docs: consequent use of github
kilchenmann Feb 2, 2021
11f8cb8
docs: update main README
kilchenmann Feb 2, 2021
2d9176a
docs(mkdocs): update docs README
kilchenmann Feb 2, 2021
bdba1f9
docs(contribution): replace knora by dsp-api
kilchenmann Feb 2, 2021
db4741f
docs: replace kui by dsp
kilchenmann Feb 2, 2021
648031b
docs: replace Kui by Dsp
kilchenmann Feb 2, 2021
177e579
docs: refactor and fix typo
kilchenmann Feb 2, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
52 changes: 51 additions & 1 deletion .github/workflows/main.yml
Expand Up @@ -90,7 +90,7 @@ jobs:
changelog-types: '[{"type": "feat", "section": "Enhancements", "hidden": false }, {"type": "fix", "section": "Bug Fixes", "hidden": false }, {"type": "chore", "section": "Maintenance", "hidden": false }, {"type": "docs", "section": "Documentation", "hidden": false }]'

publish:
name: Publish to npm
name: Publish to npm (on release only)
needs: [build-test, e2e-test]
runs-on: ubuntu-latest
env:
Expand Down Expand Up @@ -127,3 +127,53 @@ jobs:
uses: lakto/google-chat-action@main
with:
url: ${{ secrets.GOOGLE_CHAT_DSP_RELEASES_WEBHOOK_URL }}

# build documentation
docs-build-test:
name: Docs Build Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
fetch-depth: 1
- name: Set up Python 3.8
uses: actions/setup-python@v2
with:
python-version: 3.8
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r docs/requirements.txt
- name: Disk Free
run: |
df -h
docker system df
docker system prune --all --force --volumes
df -h
- name: run docs build
run: make docs-build
- name: Disk Free After
run: |
df -h
docker system df

# deploy documentation only on release
deploy-docs:
name: Deploy docs (on release only)
needs: [
docs-build-test
]
runs-on: ubuntu-latest
if: github.event_name == 'release' && startsWith(github.ref, 'refs/tags')
steps:
- name: Checkout main
uses: actions/checkout@v2
- name: Deploy docs
uses: mhausenblas/mkdocs-deploy-gh-pages@master
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
REQUIREMENTS: docs/requirements.txt
- name: Disk Free After
run: |
df -h
docker system df
1 change: 1 addition & 0 deletions .gitignore
Expand Up @@ -4,6 +4,7 @@
/dist
/tmp
/out-tsc
/site
# Only exists if Bazel was run
/bazel-out

Expand Down
31 changes: 29 additions & 2 deletions Makefile
Expand Up @@ -8,9 +8,36 @@ include vars.mk

.PHONY: clean

# Clones the knora-api git repository
#################################
# Documentation targets
#################################

.PHONY: docs-publish
docs-publish: ## build and publish docs to github Pages
mkdocs gh-deploy

.PHONY: docs-build
docs-build: ## build docs into the local 'site' folder
mkdocs build

.PHONY: docs-serve
docs-serve: ## serve docs for local viewing
mkdocs serve

.PHONY: docs-install-requirements
docs-install-requirements: ## install requirements
pip3 install -r docs/requirements.txt

.PHONY: docs-clean
docs-clean: ## cleans the project directory
@rm -rf site/

#################################
# Knora stack (DSP-API) targets
#################################

.PHONY: clone-knora-stack
clone-knora-stack:
clone-knora-stack: # Clones the knora-api git repository
@rm -rf $(CURRENT_DIR)/.tmp/knora-stack
@git clone --branch $(API_VERSION) --single-branch --depth 1 https://github.com/dasch-swiss/dsp-api.git $(CURRENT_DIR)/.tmp/knora-stack

Expand Down
193 changes: 23 additions & 170 deletions README.md
@@ -1,193 +1,46 @@
# DSP-UI-LIB — A library to easily create Knora/DSP Apps
# DSP-UI — A library to easily create DSP Apps

[![npm version](https://badge.fury.io/js/%40dasch-swiss%2Fdsp-ui.svg)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui)
[![CI](https://github.com/dasch-swiss/knora-ui-ng-lib/workflows/CI/badge.svg)](https://github.com/dasch-swiss/knora-ui-ng-lib/actions?query=workflow%3ACI)
[![CI](https://github.com/dasch-swiss/dsp-ui-lib/workflows/CI/badge.svg)](https://github.com/dasch-swiss/dsp-ui-lib/actions?query=workflow%3ACI)
[![npm downloads](https://img.shields.io/npm/dt/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui)
[![minzipped size](https://img.shields.io/bundlephobia/minzip/@dasch-swiss/dsp-ui.svg?style=flat)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui)
[![license](https://img.shields.io/npm/l/@dasch-swiss/dsp-ui.svg?style=flat)](https://github.com/dasch-swiss/dsp-ui-lib/blob/main/LICENSE)

## Introduction
<!-- This is the demo and developing environment for the [DSP-UI library (@dasch-swiss/dsp-ui)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui). -->

This is the demo and developing environment for the NPM package [DSP-UI-LIB (@dasch-swiss/dsp-ui)](https://www.npmjs.com/package/@dasch-swiss/dsp-ui).
DSP-UI is a library of angular modules enabling users to interact with [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/) to create a web application in a quick and simple way. These modules, comprised of components and directives, are written in Typescript and rely on [Angular material](https://material.angular.io).

The modules contained in DSP-UI-LIB help create an [Angular](https://angular.io) application to allow the user to connect to [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/)
in a quick and simple way.
Components and directives rely on [Angular Material](https://material.angular.io).

DSP-UI-LIB is [free software](http://www.gnu.org/philosophy/free-sw.en.html),
DSP-UI is developed by the [Data and Service Center for the Humanities](https://dasch.swiss) as [free software](http://www.gnu.org/philosophy/free-sw.en.html),
released under [GNU Affero General Public](http://www.gnu.org/licenses/agpl-3.0.en.html) license.

## Structure of This Project

This project consists of two main parts:
1. The Angular library `DSP-UI-LIB (@dasch-swiss/dsp-ui)` in `project/dsp-ui`.
1. The demo Angular Application (Playground) in `src/app`.

The Angular library contains the code that is published on NPM.
The demo Angular application's purpose is to demonstrate the library's functionality.
The library needs to be built first in order to use it withing the demo application.

The demo application uses the **locally built version** of `@dasch-swiss/dsp-ui`
which is configured in [tsconfig.json](tsconfig.json) (`compilerOptions.paths`),
see [Angular docs](https://angular.io/guide/creating-libraries#building-and-rebuilding-your-library).

## Prerequisites

### Node.js

Angular requires a [current, active LTS, or maintenance LTS](https://angular.io/guide/setup-local#prerequisites) version of Node.js.

We recommend using [n](https://www.npmjs.com/package/n),
a tool that installs and manages Node.js versions on your local system.

### NPM package manager

Angular requires the [npm package manager](https://angular.io/guide/setup-local#prerequisites).

### DSP-API

The demo application requires a running instance of [DSP-API (Knora)](https://docs.knora.org/04-publishing-deployment/getting-started/)
compatible with the version defined in [vars.mk](vars.mk).

## First steps

Clone this repository:

```bash
git clone https://github.com/dasch-swiss/dsp-ui-lib/
```

Install the dependencies with:

```bash
npm install
```

Build the library with:

```bash
npm run build-lib
```

Run the demo application:

```bash
npm run ng s
```

And access `http://localhost:4200` in your browser.

**When you are developing the library
you always have to rebuild the library before using it from the demo application.**
## Documentation

## Scripts For Development
### ➡ [Getting started](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/getting-started/)

The following scripts can be used for development:
### Library modules

### Testing
- `npm test`: runs the unit tests of the demo application and the lib's unit tests.
- `npm test-lib`: runs the lib's unit tests in headless mode (no browser UI).
- `npm test-lib-local`: runs the lib's unit test with the browser UI (for local development of the lib).
- `npm run webdriver-update`: installs Chrome webdriver in the required version for the E2E tests.
- `npm run e2e`: runs the E2E tests from the demo application, see section [E2E Tests](README.md#Unit and E2E Tests).
The library consists of four Angular modules that are briefly described below.

### Building
- `npm run build`: builds the lib in productive mode, see section [Building the Library](README.md#Building the Library).
- `npm run build-dev`: builds the lib in development mode, see section [Building the Library](README.md#Building the Library).
- `npm build-app`: builds the demo application in productive mode, see also section [Run the application in productive mode](README.md#Run the application in productive mode)
- `npm run yalc-publish-lib`: builds the lib and publishes it locally using `yalc`.
### ➡ [DspCoreModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/core/)

## Library Build Options
*Services for API requests*
> DspCoreModule is a configuration handler for [`@dasch-swiss/dsp-js`](https://www.npmjs.com/package/@dasch-swiss/dsp-js) which offers all the services to make [DSP-API requests](https://docs.dasch.swiss/developers/knora/api-reference/queries/).

The library is built in productive mode for publication, using [tsconfig.lib.prod.json](projects/dsp-ui/tsconfig.lib.prod.json).
### ➡ [DspViewerModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/viewer/)

To perform additional checks during development, the library can be built in development mode,
using [tsconfig.lib.json](projects/dsp-ui/tsconfig.lib.json). Development builds use Ivy and perform [strict template checks](https://angular.io/guide/template-typecheck#template-type-checking).
*Resources, Properties, Lists, Value components*
> DspViewerModule contains object components to show a resource class representation, the property gui-elements and various view frameworks.

## Unit Tests and E2E Tests
### ➡ [DspSearchModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/search/)

There are unit tests for the lib (`projects/dsp-ui/src`)
and some basic unit tests for the demo application playground components (`src/app`).
*Search panel for all kind of search queries*
> DspSearchModule allows to make full text or extended searches in DSP-API. Filter by resource class and its properties related to an ontology.

The E2E tests have to be run from the demo application.
Unlike the unit tests, they require a running instance of DSP-API compatible with the release specified in [vars.mk](vars.mk).
Before running the E2E tests, reload the data in DSP-API's db.
The E2E tests can be run as follows:
- `npm run webdriver-update`
- `npm run e2e`
### ➡ [DspActionModule](https://dasch-swiss.github.io/dsp-ui-lib/how-to-use/action/)

## Demo Application (Playground)

### Add a New Component to the Demo Application

The demo app demonstrates the functionality of dsp-ui-lib's modules.
By default, the demo app's main component routes to the page demonstrating the resource viewer in read mode.

Before adding a new component to the demo app,
check if the desired demo could be added to an existing component of the demo app.

Follow these steps to add a new component to the demo app:
- create a new component in the demo app:
- create a new component using Angular CLI in `src/app`
- demonstrate a part of dsp-ui-lib (component, service etc.) in the new component of the demo app
- in `AppRoutingModule` and `AppComponent`'s template, set up the routing for your new component in the demo app.

### Run the Application Locally in Dev Mode With Live Reloading

To make changes to the DSP-UI and have your changes reflected immediately upon saving, follow these steps:

- run `npm run build-watchful-lib-dev` from the project root directory
- open a new tab and run `npm run start` from the project root directory
- now, anytime you make a change to DSP-UI and save, the library will be re-built and the webpage will refresh and you will see the changes

### Run the Application in Productive Mode

To simulate a production environment, the application should be built with optimization and served locally
(not in dev mode, but from a local web server).

- Install `nginx` on your system, e.g. `brew install nginx` for mac OS. Check the [documentation](https://linux.die.net/man/8/nginx) for more information.
- Create a configuration file for the test application.
The example defines a configuration file `/usr/local/etc/nginx/servers/dspuiapp.conf` for macOS.
Substitute `$abs_path_to_lib` with the actual absolute path on your system pointing to the project root.
Substitute `$dsp-ui_folder_name` with the folder name of the app build in `dist`.

```nginx
server {
listen 8090;
server_name dspuiapp.local;
root /$abs_path_to_lib/dist/$dsp-ui_folder_name;

location / {
try_files $uri $uri/ /index.html;
}

access_log /usr/local/etc/nginx/logs/dspuiapp.local.access.log;
}
```

- Add an entry to your `/etc/hosts`: `127.0.0.1 dspuiapp.local`
- Create an empty file `dspuiapp.local.access.log` in `/usr/local/etc/nginx/logs`
(you might have to create the folder `logs` first)
- Start `nginx` (if `nginx` is already running, stop it first: `nginx`: `nginx -s stop`)
- Build the library: `npm run build-lib`
- Build the test app with optimization: `npm run build-app`
- Access it via <http://dspuiapp.local:8090>

### Build and Run the Application in Docker

To build and run the application in Docker, do the following:

1. `docker build --tag app:0.1 .` (you can use any tag name you want)
2. `docker run -v ~/localdir/config.prod.json:/public/config/config.prod.json --publish 4200:4200 --detach --name myname app:0.1`

The first step builds the lib and app in Docker. Make sure to delete the contents of the `dist` folder on your local system first.

The second step runs a container based on the image built in the previous step:

- `-v` mounts a config file from your local file system in the Docker container, so you can set the config.
- `--publish` maps the port on your local machine to the port in the Docker container.

You can now access the app on your local machine under <http://localhost:4200/>.
*Special pipes and buttons*
> DspActionModule contains special pipes to sort lists or to get the index key in arrays, but also directives and components for images, sort buttons and s.o.

## Contribution
See our [contribution guidelines](projects/dsp-ui/Contribution.md).

If you would like to contribute to the development of the DSP-UI modules alongside us, please consult the [general DSP contribution guidelines](https://docs.dasch.swiss/developers/dsp/contribution/) or the [DSP-UI specific contribution guidelines](https://dasch-swiss.github.io/dsp-ui-lib/how-to-contribute/) and the [design documentation](https://dasch-swiss.github.io/dsp-ui-lib/how-to-contribute/design-documentation/).