diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 7ea8650257..2d99cf05a9 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -68,3 +68,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 diff --git a/Makefile b/Makefile index c070fa868d..b004898b78 100644 --- a/Makefile +++ b/Makefile @@ -6,6 +6,33 @@ CURRENT_DIR := $(shell dirname $(realpath $(firstword $(MAKEFILE_LIST)))) include vars.mk +################################# +# 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/ + +################################# +# Build and publish targets +################################# .PHONY: build-dsp-app-image build-dsp-app-image: ## build DSP APP image locally docker build -t $(DSP_APP_IMAGE) . diff --git a/README.md b/README.md index c7fb356832..89063db7f5 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This app is a simple user interface for the Data and Service Center for the Humanities DaSCH, which uses the DSP-API/Knora server application in the backend. It's a system for annotation and linkage of resources in arts and humanities. -DSP-APP implements [DSP-JS-LIB](https://www.npmjs.com/package/@dasch-swiss/dsp-js) to connect with [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/). DSP-API is a software framework for storing, sharing, and working with primary resources and data in the humanities. +DSP-APP implements [DSP-JS-LIB](https://www.npmjs.com/package/@dasch-swiss/dsp-js) to connect with [DSP-API](https://docs.dasch.swiss/developers/knora/api-reference/). DSP (DaSCH Service Platform) is a software framework for storing, sharing, and working with primary resources and data in the humanities. Additionaly it's built with [DSP-UI-LIB](https://www.npmjs.com/package/@dasch-swiss/dsp-ui) — reusable DSP specific Angular modules. @@ -16,56 +16,34 @@ Please check our [DSP Release Compatibility Matrix](https://docs.google.com/spre DSP-APP is [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. -## Development server +## Documentation -Run `ng serve` for a dev server. Navigate to `http://0.0.0.0:4200/`. The app will automatically reload if you change any of the resource files. +### User guide -## Code scaffolding +➡ [for current deployed version](https://docs.dasch.swiss/user-guide/) -Run `ng generate component component-name` to generate a new component. You can -also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. +➡ [for development version](https://dasch-swiss.github.io/dsp-app/how-to-use) -## Build +### Developer docs -Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. +➡ [for developers](https://dasch-swiss.github.io/dsp-app/how-to-contribute) -## Running unit tests +## Contribution -Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). +If you would like to contribute to the development of the DSP-APP alongside us, please consult the [general DSP contribution guidelines](https://docs.dasch.swiss/developers/dsp/contribution/). -## Running end-to-end tests +### Work on GitHub -Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). +DSP-APP has two main branches at the moment: -## Further help - -To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md). - -## Documentation / User guidelines - -We built the user guidelines and developer documentation with [MkDocs](https://www.mkdocs.org/) in a separate [repository](https://github.com/dasch-swiss/dsp-docs). The user guide is published on [docs.dasch.swiss/user-guide](https://docs.dasch.swiss/user-guide). - -## Work on GitHub - -### "main" branch +#### "main" branch - use the branch "main" to work on the DSP-ADMIN app. Any changes should be created in branches from "main" and should be merged into the "main" branch. -### "develop" branch +#### "develop" branch - use the branch "develop" to work on the whole DSP-APP app (admin + research parts). Any new developments should be created in branches from "develop" and should be merged into the "develop" branch. -## Publish a new version to DockerHub - -Before publishing: - -- Update README if necessary and commit the changes. - -- Be sure that all dependencies to DSP-UI-LIB, DSP-JS-LIB and DSP-API are set to the correct version. - -A new version will be published with each Github release as it's part of Github actions' workflow. To make a new release, go to and update the draft called "Next release" by changing: - -- The tag version and the release title (same name) with the version number, e.g. `v3.0.0` or `v3.0.0-rc.0` -- If this is a pre-release, check the box "This is a pre-release" +### Documentation / User guidelines -New package will be available on . +We built the user guidelines and developer documentation with [MkDocs](https://www.mkdocs.org/). Get more information in the appropriate [README](https://github.com/dasch-swiss/dsp-app/blob/main/docs/README.md). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000000..e528ca1bbe --- /dev/null +++ b/docs/README.md @@ -0,0 +1,89 @@ +# DSP-APP Documentation + +This is the DSP-APP documentation, based on [MkDocs](https://www.mkdocs.org) and published +under [http://dasch-swiss.github.io/dsp-app](http://dasch-swiss.github.io/dsp-app). + +## Contribute + +If you would like to add your own contributions to the docs, please read the following information regarding the file structure to ensure you follow the same structure. + +### File structure + +The documentation consists of three main topics with subordinate themes: + +1. **index** contains all information about the DSP-APP +1. **how-to-use** contains the DSP-APP user guide + - Index = Introduction: All about login, registration and DSP APP information in general. + - Project = All about project administration; part of DSP-ADMIN + - User = All about user administration; part of DSP-ADMIN + - System = All about system administration; part of DSP-ADMIN + - Data = All about data management; part of VRE. In the current DSP-APP ADMIN version it's commented out +1. **how-to-contribute** contains all information for people who wants to contribute to DSP-APP + - Index = How to contribute incl. link to the general DSP contribution guidelines () + - Release Notes = Contains the CHANGELOG file of DSP-APP + +Images like screenshots and so on have to be stored in `assets/images`. + +The `mkdocs.yml` file is present in the top-level directory of the repo and the source files are in the `docs/` folder. + +Plugins have to be defined in `requirements.txt` and in the github actions workflow `deploy-docs` step under `EXTRA_PACKAGES`. + +## Getting Started + +To run the documentation locally you'll need [Python](https://www.python.org/) installed, as well as the Python package manager [pip](http://pip.readthedocs.io/en/stable/installing/). You can check if you already have these installed by running the following commands from the command line: + +```shell +$ python --version +Python 3.8.2 +$ pip --version +pip 20.0.2 from /usr/local/lib/python3.8/site-packages/pip (python 3.8) +``` + +MkDocs supports Python versions 3.5, 3.6, 3.7, 3.8, and pypy3. + +### Installing dependencies + +Install the required packages by running the following command: + +```shell +make docs-install-requirements +``` + +### Running the documentation locally + +MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you're in the same directory as the `mkdocs.yml` (repository's root folder) configuration file, and then start the server by running the following command: + +```shell +$ make docs-serve +INFO - Building documentation... +INFO - Cleaning site directory +[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000 +[I 160402 15:50:43 handlers:58] Start watching changes +[I 160402 15:50:43 handlers:60] Start detecting changes +``` + +Open up in your browser, and you'll see the documentation start page being. + +In case you need to clean the project directory, run: + +```shell +make docs-clean +``` + +To get some help about the `make` commands, run: + +```shell +make help +``` + +### Building the documentation + +To build the documentation, run: + +```shell +make docs-build +``` + +### Deploying github page + +On each release of DSP-APP, a github action script will build and deploy the documentation on [dasch-swiss.github.io/dsp-app](https://dasch-swiss.github.io/dsp-app). Behind the scenes, MkDocs builds the documentation and uses the [mkdocs-deploy-gh-pages](https://github.com/marketplace/actions/deploy-mkdocs) actions script to deploy them to the gh-pages. That's it! diff --git a/docs/assets/fonts/roboto-v19-latin-300.eot b/docs/assets/fonts/roboto-v19-latin-300.eot new file mode 100644 index 0000000000..574375d40b Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.svg b/docs/assets/fonts/roboto-v19-latin-300.svg new file mode 100644 index 0000000000..4ded944a8b --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-300.svg @@ -0,0 +1,312 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-300.ttf b/docs/assets/fonts/roboto-v19-latin-300.ttf new file mode 100644 index 0000000000..57a24e82f2 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.woff b/docs/assets/fonts/roboto-v19-latin-300.woff new file mode 100644 index 0000000000..2f6bdb5e74 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-300.woff2 b/docs/assets/fonts/roboto-v19-latin-300.woff2 new file mode 100644 index 0000000000..ef8c8836bd Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-300.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.eot b/docs/assets/fonts/roboto-v19-latin-500.eot new file mode 100644 index 0000000000..2ec7bdd750 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.svg b/docs/assets/fonts/roboto-v19-latin-500.svg new file mode 100644 index 0000000000..67eecf442f --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-500.svg @@ -0,0 +1,305 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-500.ttf b/docs/assets/fonts/roboto-v19-latin-500.ttf new file mode 100644 index 0000000000..dd04ff19d0 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.woff b/docs/assets/fonts/roboto-v19-latin-500.woff new file mode 100644 index 0000000000..869925869a Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-500.woff2 b/docs/assets/fonts/roboto-v19-latin-500.woff2 new file mode 100644 index 0000000000..6362d7f64a Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-500.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.eot b/docs/assets/fonts/roboto-v19-latin-700.eot new file mode 100644 index 0000000000..0168f09bca Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.svg b/docs/assets/fonts/roboto-v19-latin-700.svg new file mode 100644 index 0000000000..11db87dd0e --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-700.svg @@ -0,0 +1,309 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-700.ttf b/docs/assets/fonts/roboto-v19-latin-700.ttf new file mode 100644 index 0000000000..ea06a634fe Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.woff b/docs/assets/fonts/roboto-v19-latin-700.woff new file mode 100644 index 0000000000..0f14effba0 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-700.woff2 b/docs/assets/fonts/roboto-v19-latin-700.woff2 new file mode 100644 index 0000000000..32b25eee7c Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-700.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.eot b/docs/assets/fonts/roboto-v19-latin-italic.eot new file mode 100644 index 0000000000..0753b8839e Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.svg b/docs/assets/fonts/roboto-v19-latin-italic.svg new file mode 100644 index 0000000000..4d59797103 --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-italic.svg @@ -0,0 +1,323 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-italic.ttf b/docs/assets/fonts/roboto-v19-latin-italic.ttf new file mode 100644 index 0000000000..bdbb10850f Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.woff b/docs/assets/fonts/roboto-v19-latin-italic.woff new file mode 100644 index 0000000000..b940dbcb78 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-italic.woff2 b/docs/assets/fonts/roboto-v19-latin-italic.woff2 new file mode 100644 index 0000000000..2741d4f082 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-italic.woff2 differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.eot b/docs/assets/fonts/roboto-v19-latin-regular.eot new file mode 100644 index 0000000000..4f34800914 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.eot differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.svg b/docs/assets/fonts/roboto-v19-latin-regular.svg new file mode 100644 index 0000000000..627f5a368c --- /dev/null +++ b/docs/assets/fonts/roboto-v19-latin-regular.svg @@ -0,0 +1,308 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/fonts/roboto-v19-latin-regular.ttf b/docs/assets/fonts/roboto-v19-latin-regular.ttf new file mode 100644 index 0000000000..a97385dfdd Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.ttf differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.woff b/docs/assets/fonts/roboto-v19-latin-regular.woff new file mode 100644 index 0000000000..69c8825405 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.woff differ diff --git a/docs/assets/fonts/roboto-v19-latin-regular.woff2 b/docs/assets/fonts/roboto-v19-latin-regular.woff2 new file mode 100644 index 0000000000..1a53701510 Binary files /dev/null and b/docs/assets/fonts/roboto-v19-latin-regular.woff2 differ diff --git a/docs/assets/icons/dasch-favicon.ico b/docs/assets/icons/dasch-favicon.ico new file mode 100644 index 0000000000..0d9a7751eb Binary files /dev/null and b/docs/assets/icons/dasch-favicon.ico differ diff --git a/docs/assets/icons/dasch-icon-white.svg b/docs/assets/icons/dasch-icon-white.svg new file mode 100644 index 0000000000..396dd5358d --- /dev/null +++ b/docs/assets/icons/dasch-icon-white.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/assets/icons/favicon.png b/docs/assets/icons/favicon.png new file mode 100644 index 0000000000..858b838fbe Binary files /dev/null and b/docs/assets/icons/favicon.png differ diff --git a/docs/assets/images/dasch-favicon.ico b/docs/assets/images/dasch-favicon.ico new file mode 100644 index 0000000000..0d9a7751eb Binary files /dev/null and b/docs/assets/images/dasch-favicon.ico differ diff --git a/docs/assets/images/dasch-icon-white.svg b/docs/assets/images/dasch-icon-white.svg new file mode 100644 index 0000000000..396dd5358d --- /dev/null +++ b/docs/assets/images/dasch-icon-white.svg @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/docs/assets/images/dashboard-header.png b/docs/assets/images/dashboard-header.png new file mode 100644 index 0000000000..23c4924710 Binary files /dev/null and b/docs/assets/images/dashboard-header.png differ diff --git a/docs/assets/images/data-model-add-property.png b/docs/assets/images/data-model-add-property.png new file mode 100644 index 0000000000..1f6e6db7f8 Binary files /dev/null and b/docs/assets/images/data-model-add-property.png differ diff --git a/docs/assets/images/data-model-add-source.png b/docs/assets/images/data-model-add-source.png new file mode 100644 index 0000000000..0859452752 Binary files /dev/null and b/docs/assets/images/data-model-add-source.png differ diff --git a/docs/assets/images/data-model-edit-source.png b/docs/assets/images/data-model-edit-source.png new file mode 100644 index 0000000000..84145cfaa7 Binary files /dev/null and b/docs/assets/images/data-model-edit-source.png differ diff --git a/docs/assets/images/data-model-example.png b/docs/assets/images/data-model-example.png new file mode 100644 index 0000000000..fae272be10 Binary files /dev/null and b/docs/assets/images/data-model-example.png differ diff --git a/docs/assets/images/data-model-init.png b/docs/assets/images/data-model-init.png new file mode 100644 index 0000000000..cbcbae1d4d Binary files /dev/null and b/docs/assets/images/data-model-init.png differ diff --git a/docs/assets/images/diagram-data-model.png b/docs/assets/images/diagram-data-model.png new file mode 100644 index 0000000000..a0971d041a Binary files /dev/null and b/docs/assets/images/diagram-data-model.png differ diff --git a/docs/assets/images/favicon.png b/docs/assets/images/favicon.png new file mode 100644 index 0000000000..858b838fbe Binary files /dev/null and b/docs/assets/images/favicon.png differ diff --git a/docs/assets/images/material-mat-display-titles.png b/docs/assets/images/material-mat-display-titles.png new file mode 100644 index 0000000000..bcb4daad91 Binary files /dev/null and b/docs/assets/images/material-mat-display-titles.png differ diff --git a/docs/assets/images/material-typography.png b/docs/assets/images/material-typography.png new file mode 100644 index 0000000000..15383cfd7a Binary files /dev/null and b/docs/assets/images/material-typography.png differ diff --git a/docs/assets/images/mock-source-new-edit.png b/docs/assets/images/mock-source-new-edit.png new file mode 100644 index 0000000000..fdfa69f5e7 Binary files /dev/null and b/docs/assets/images/mock-source-new-edit.png differ diff --git a/docs/assets/images/project-collaboration.png b/docs/assets/images/project-collaboration.png new file mode 100644 index 0000000000..9be955d157 Binary files /dev/null and b/docs/assets/images/project-collaboration.png differ diff --git a/docs/assets/images/project-create-new.png b/docs/assets/images/project-create-new.png new file mode 100644 index 0000000000..a3c87faf63 Binary files /dev/null and b/docs/assets/images/project-create-new.png differ diff --git a/docs/assets/images/project-info.png b/docs/assets/images/project-info.png new file mode 100644 index 0000000000..4c28943b01 Binary files /dev/null and b/docs/assets/images/project-info.png differ diff --git a/docs/assets/images/project-list.png b/docs/assets/images/project-list.png new file mode 100644 index 0000000000..fd038b3ae3 Binary files /dev/null and b/docs/assets/images/project-list.png differ diff --git a/docs/assets/images/project-lists.png b/docs/assets/images/project-lists.png new file mode 100644 index 0000000000..cca3733fc1 Binary files /dev/null and b/docs/assets/images/project-lists.png differ diff --git a/docs/assets/images/resource-view-with-image.png b/docs/assets/images/resource-view-with-image.png new file mode 100644 index 0000000000..a47cff1877 Binary files /dev/null and b/docs/assets/images/resource-view-with-image.png differ diff --git a/docs/assets/images/search-3modes.png b/docs/assets/images/search-3modes.png new file mode 100644 index 0000000000..640ab3319a Binary files /dev/null and b/docs/assets/images/search-3modes.png differ diff --git a/docs/assets/images/search-advanced-diagram.png b/docs/assets/images/search-advanced-diagram.png new file mode 100644 index 0000000000..4122b28f3d Binary files /dev/null and b/docs/assets/images/search-advanced-diagram.png differ diff --git a/docs/assets/images/search-advanced-link.png b/docs/assets/images/search-advanced-link.png new file mode 100644 index 0000000000..c4d02d6e80 Binary files /dev/null and b/docs/assets/images/search-advanced-link.png differ diff --git a/docs/assets/images/search-advanced-mockup.png b/docs/assets/images/search-advanced-mockup.png new file mode 100644 index 0000000000..8e3ef9a33e Binary files /dev/null and b/docs/assets/images/search-advanced-mockup.png differ diff --git a/docs/assets/images/search-advanced.png b/docs/assets/images/search-advanced.png new file mode 100644 index 0000000000..c67ea5a95f Binary files /dev/null and b/docs/assets/images/search-advanced.png differ diff --git a/docs/assets/images/search-expert-gravsearch-mockup.png b/docs/assets/images/search-expert-gravsearch-mockup.png new file mode 100644 index 0000000000..fbfdcd71ee Binary files /dev/null and b/docs/assets/images/search-expert-gravsearch-mockup.png differ diff --git a/docs/assets/images/search-expert-link.png b/docs/assets/images/search-expert-link.png new file mode 100644 index 0000000000..26058f2be3 Binary files /dev/null and b/docs/assets/images/search-expert-link.png differ diff --git a/docs/assets/images/search-expert.png b/docs/assets/images/search-expert.png new file mode 100644 index 0000000000..155a8a6d5f Binary files /dev/null and b/docs/assets/images/search-expert.png differ diff --git a/docs/assets/images/search-fulltext-filterByProject.png b/docs/assets/images/search-fulltext-filterByProject.png new file mode 100644 index 0000000000..11f9b84db5 Binary files /dev/null and b/docs/assets/images/search-fulltext-filterByProject.png differ diff --git a/docs/assets/images/search-history.png b/docs/assets/images/search-history.png new file mode 100644 index 0000000000..66c0e8568e Binary files /dev/null and b/docs/assets/images/search-history.png differ diff --git a/docs/assets/images/search-results-grid-list-mockup.png b/docs/assets/images/search-results-grid-list-mockup.png new file mode 100644 index 0000000000..2bb6bf15fc Binary files /dev/null and b/docs/assets/images/search-results-grid-list-mockup.png differ diff --git a/docs/assets/images/search-results-grid.png b/docs/assets/images/search-results-grid.png new file mode 100644 index 0000000000..013fbc2136 Binary files /dev/null and b/docs/assets/images/search-results-grid.png differ diff --git a/docs/assets/images/search-results-list.png b/docs/assets/images/search-results-list.png new file mode 100644 index 0000000000..b4e01db3ef Binary files /dev/null and b/docs/assets/images/search-results-list.png differ diff --git a/docs/assets/images/search-results-simple-list-mockup.png b/docs/assets/images/search-results-simple-list-mockup.png new file mode 100644 index 0000000000..4fb0893e9c Binary files /dev/null and b/docs/assets/images/search-results-simple-list-mockup.png differ diff --git a/docs/assets/images/search-results-table-mockup.png b/docs/assets/images/search-results-table-mockup.png new file mode 100644 index 0000000000..e5c07b042c Binary files /dev/null and b/docs/assets/images/search-results-table-mockup.png differ diff --git a/docs/assets/images/search.svg b/docs/assets/images/search.svg new file mode 100755 index 0000000000..421ca4df01 --- /dev/null +++ b/docs/assets/images/search.svg @@ -0,0 +1 @@ +Search diff --git a/docs/assets/images/share-export-menu.png b/docs/assets/images/share-export-menu.png new file mode 100644 index 0000000000..093aa96ffa Binary files /dev/null and b/docs/assets/images/share-export-menu.png differ diff --git a/docs/assets/images/source-compare-viewer.png b/docs/assets/images/source-compare-viewer.png new file mode 100644 index 0000000000..e5685e4f6f Binary files /dev/null and b/docs/assets/images/source-compare-viewer.png differ diff --git a/docs/assets/images/source-form.png b/docs/assets/images/source-form.png new file mode 100644 index 0000000000..fdfa69f5e7 Binary files /dev/null and b/docs/assets/images/source-form.png differ diff --git a/docs/assets/images/source-graph-view.png b/docs/assets/images/source-graph-view.png new file mode 100644 index 0000000000..5607192179 Binary files /dev/null and b/docs/assets/images/source-graph-view.png differ diff --git a/docs/assets/images/source-selected-fullframe.png b/docs/assets/images/source-selected-fullframe.png new file mode 100644 index 0000000000..77ef91a17f Binary files /dev/null and b/docs/assets/images/source-selected-fullframe.png differ diff --git a/docs/assets/images/source-selected-one.png b/docs/assets/images/source-selected-one.png new file mode 100644 index 0000000000..41d3095f98 Binary files /dev/null and b/docs/assets/images/source-selected-one.png differ diff --git a/docs/assets/images/source-selected-three.png b/docs/assets/images/source-selected-three.png new file mode 100644 index 0000000000..3f8142b5e3 Binary files /dev/null and b/docs/assets/images/source-selected-three.png differ diff --git a/docs/assets/images/system-all-projects.png b/docs/assets/images/system-all-projects.png new file mode 100644 index 0000000000..14bd46f552 Binary files /dev/null and b/docs/assets/images/system-all-projects.png differ diff --git a/docs/assets/images/system-all-users.png b/docs/assets/images/system-all-users.png new file mode 100644 index 0000000000..2ba9071023 Binary files /dev/null and b/docs/assets/images/system-all-users.png differ diff --git a/docs/assets/images/system-change-user-pwd.png b/docs/assets/images/system-change-user-pwd.png new file mode 100644 index 0000000000..8d39b8ea29 Binary files /dev/null and b/docs/assets/images/system-change-user-pwd.png differ diff --git a/docs/assets/images/system-manage-project-membership.png b/docs/assets/images/system-manage-project-membership.png new file mode 100644 index 0000000000..ba7ef381c9 Binary files /dev/null and b/docs/assets/images/system-manage-project-membership.png differ diff --git a/docs/assets/images/system-user-menu.png b/docs/assets/images/system-user-menu.png new file mode 100644 index 0000000000..dcf1d3bed5 Binary files /dev/null and b/docs/assets/images/system-user-menu.png differ diff --git a/docs/assets/images/user-account.png b/docs/assets/images/user-account.png new file mode 100644 index 0000000000..1a70ae6259 Binary files /dev/null and b/docs/assets/images/user-account.png differ diff --git a/docs/assets/images/user-edit-profile.png b/docs/assets/images/user-edit-profile.png new file mode 100644 index 0000000000..7aa65f2df0 Binary files /dev/null and b/docs/assets/images/user-edit-profile.png differ diff --git a/docs/assets/images/user-profile.png b/docs/assets/images/user-profile.png new file mode 100644 index 0000000000..83562b3d19 Binary files /dev/null and b/docs/assets/images/user-profile.png differ diff --git a/docs/assets/images/usermenu-to-userprofile.png b/docs/assets/images/usermenu-to-userprofile.png new file mode 100644 index 0000000000..c73918d98a Binary files /dev/null and b/docs/assets/images/usermenu-to-userprofile.png differ diff --git a/docs/assets/style/theme.css b/docs/assets/style/theme.css new file mode 100644 index 0000000000..38339e095c --- /dev/null +++ b/docs/assets/style/theme.css @@ -0,0 +1,4 @@ +.md-header, +.md-tabs { + background-color: rgb(89, 73, 167) !important; +} diff --git a/docs/how-to-contribute/docs-documentation.md b/docs/how-to-contribute/docs-documentation.md new file mode 100644 index 0000000000..4129e67ee0 --- /dev/null +++ b/docs/how-to-contribute/docs-documentation.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/how-to-contribute/index.md b/docs/how-to-contribute/index.md new file mode 100644 index 0000000000..3a732f7e62 --- /dev/null +++ b/docs/how-to-contribute/index.md @@ -0,0 +1,27 @@ +# How to Contribute to this Project + + +## Development server + +Run `ng serve` for a dev server. Navigate to `http://0.0.0.0:4200/`. The app will automatically reload if you change any of the resource files. + +## Code scaffolding + +Run `ng generate component component-name` to generate a new component. You can +also use `ng generate directive|pipe|service|class|guard|interface|enum|module`. + +## Build + +Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory. Use the `--prod` flag for a production build. + +## Running unit tests + +Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io). + +## Running end-to-end tests + +Run `ng e2e` to execute the end-to-end tests via [Protractor](http://www.protractortest.org/). + +## Further help + +To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI README](https://github.com/angular/angular-cli/blob/master/README.md). diff --git a/docs/how-to-contribute/release-notes.md b/docs/how-to-contribute/release-notes.md new file mode 100644 index 0000000000..c214565a75 --- /dev/null +++ b/docs/how-to-contribute/release-notes.md @@ -0,0 +1,3 @@ +{% + include-markdown "../../CHANGELOG.md" +%} diff --git a/docs/how-to-use/data.md b/docs/how-to-use/data.md new file mode 100644 index 0000000000..57804f65bb --- /dev/null +++ b/docs/how-to-use/data.md @@ -0,0 +1,167 @@ +# Data management + +Once your [data model](/user-guide/project/#data-model) is ready, you're able to add data. The DSP-APP offers several possibilities to add data, whether you are starting from scratch or importing data from another program. + +## Start from scratch +⚠ *NOT YET IMPLEMENTED* (only mockups are presented) + +When a project starts from scratch, you will enter and generate new data directly in the DSP-APP itself. Generating new data can be done one by one with a form or with a table-based (Excel like) tool. + +- Upload the files, e.g., the actual audio file of an interview or images of the photographs discussed in the interview +- Augment the metadata +- In case of interview transcriptions from audio or video files, DSP-APP will offer a simple transcription tool + +![Create new source e.g. upload audio file of an interview.](../assets/images/mock-source-new-edit.png)*Create new source; e.g. upload audio file of an interview.* + +--- + +### Organize data and create additional sources +⚠ *NOT YET IMPLEMENTED* + +The workspace of the DSP-APP includes tools to connect different sources, even if they're not in the same project (linkage), to comment on a source and on their metadata fields (annotate), and to transcribe audio-visual material. These actions will generate more data and will help to find specific sources and their relations easily. +It's possible to collect different sources and to store them in an individual collection. You can define more than one collection. You can share collections and invite other users to collaborate. + +--- + +## Search and browse + +DSP-APP offers the possibility to the user to search in 3 different ways: **full text** search, **advanced** search and **expert** search (Gravsearch query). The search bar is always available in the header of each page, whether logged in or out. + +![Search bar with the 3 search modes: full text, advanced and expert](../assets/images/search-3modes.png) + +### Full text search + +Full text search performs queries including one or more terms or phrases, and returns data that matches search conditions. By default, the search is performed in all projects stored in Knora. However, it is possible to filter by project using the menu "Filter by project" on the left side of the search bar. + +![Filter your full text search by specific project](../assets/images/search-fulltext-filterByProject.png)*https://app2.dasch.swiss - Search 1: Full text search* + +When clicking on the search bar, the search history panel is displayed. The **10** last searches are registered. It is also possible to clear the search history list (*Clear list* button at the bottom of the panel). + +![Search history panel](../assets/images/search-history.png)*Search history list is accessible for the full text search from any webpage.* + +Special syntax: + +- asterisk* can be used as a wildcard symbol +- "quotation marks" searches for the whole pattern + +--- + +### Advanced search + +![Advanced search link is findable in the search menu at the right of the full text search field.](../assets/images/search-advanced-link.png) + +The advanced search allows you to filter by project, by source type, or by the metadata of source types. Each filter can be standalone or combined. The metadata field can be precisely filtered with criteria such as "contains", "is like", "equals to", "exists" or in case of a date value with "before" or "after". + +In addition, for a metadata field that is connected to another source type, it's possible to filter by this second source type. + +![Search 2: Advanced search offers many filter combinations and is a powerful search tool.](../assets/images/search-advanced.png)*https://app2.dasch.swiss/search/advanced - Search 2: Advanced search offers many filter combinations and is a powerful search tool.* + +Currently, it is possible to search for only **one** source. + +--- + +### Expert search + +![Expert search link is findable in the search menu at the right of the full text search field.](../assets/images/search-expert-link.png) + +The expert search can be more powerful than the advanced search, but requires knowing how to use the query language Gravsearch (based on SparQL and developed by the DaSCH team). With Gravsearch, expert users can build searches by combining text-related criteria with any other criteria. + +**For example**: you could search for a page in a manuscript that contains a certain element and also mentions a person, who lived in the same country as another person, who is the author of another author. + +![Expert search is a text area in which you can create Gravsearch queries.](../assets/images/search-expert.png)*https://app2.dasch.swiss/search/expert - Search 3: Expert search is a text area in which you can create Gravsearch queries. Here is the default example you can find in the app.* + +To learn Gravsearch, go to the Knora documentation [→ Gravsearch](https://docs.knora.org/paradox/03-apis/api-v2/query-language.html) + +--- + +## Search results + + +### Simple list +The results of the search are displayed in an organised list with a small preview. You can select one result at a time to get more information. + +![Search result 1: Simple list of results, similar to Google's list of results.](../assets/images/search-results-list.png)*Search result 1: Simple list of results, similar to Google's list of results.* + +⚠ *NOT YET IMPLEMENTED* +It is not possible yet to sort or order by criteria when searching with the full text search, use the advanced search or the expert search instead to get back sorted results. + +--- + +### Grid list: Lighttable + +The results of the search are displayed in a grid list with a big preview. You can select one result at a time to get more information. + +![Search result 2: A kind of preview list, inspired by Pinterest.com.](../assets/images/search-results-grid.png)*Search result 2: A preview list where the results are presented in tiles.* + +--- + +### Table: Excel-like view +⚠ *NOT YET IMPLEMENTED* + +The search results are displayed in a table with the option to sort them. This layout is enabled when the search has been performed with **only one source type**. +Each column of the table corresponds to one metadata. + +![Search result 3: An Excel-like table view to edit multiple sources at once.](../assets/images/search-results-table-mockup.png)*Search result 3: An Excel-like table view to edit multiple sources at once.* + +--- + +## Do research and work on your data + +Once you have found the desired sources, you can (re)view them and annotate the source itself, the media file, or single metadata values. If you select more than one source, you can compare them in a side-by-side view, link them, edit them all at once, or save them in a collection. A collection is similar to a playlist in a music app or shopping basket in an online store. + +### Display a source +⚠ *WORK IN PROGRESS* + +The DSP-APP offers different source views for different media types. There's a viewer for still images, moving images, audio and document files. You can open them from the list of search results. Depending on the media type, DSP-APP offers different tools to work on the source. + +In a still image source, you're able to draw regions on the image and to annotate or transcribe this region. Usually, a still image source is used for book pages, photographs, postcards, letters etc. + +In time-based sources like moving image or audio document, you can mark sequences on the timeline. A transcription tool helps to annotate and to transcribe the sequence. + +![Single source view. The source type in this example is "Photo".](../assets/images/resource-view-with-image.png)*Single source view. The source type in this example is "Page".* + +DSP-APP will offer a graph view to visualize the connection of a selected source. The graph view is a powerful tool because you will find more information about the source by clicking through the nodes. + +![Graph view of a single source.](../assets/images/source-graph-view.png)*Graph view of a single source.* + +Additionally, you can work on the source directly, e.g, transcribe a moving image or a taped interview or mark regions of interest on still images and on documents. + +![Single source fullframe view with the transcription tool at the bottom. The source type in this example is "Video" with a table-based sequence protocol on the right hand-side.](../assets/images/source-selected-fullframe.png)*Single source fullframe view with the transcription tool at the bottom. The source type in this example is "Video" with a table-based sequence protocol on the right hand-side.* + +--- + +### Select more than one source +⚠ *NOT YET IMPLEMENTED* + +![Three sources selected; what do you want to do with them?](../assets/images/source-selected-three.png)*Three sources are selected; what do you want to do with them?* + +By selecting more than one source, you will be able to edit them all at once, add them to a collection, share or connect them. +Or you could compare the sources (see [Compare the sources](/user-guide/data/#compare-the-sources)). + +--- + +### Compare the sources +⚠ *NOT YET IMPLEMENTED* + +You will be able to compare from two to six source objects at the same time side by side. + +![Compare 2 to 6 sources with each other, similar to the Mirador web app.](../assets/images/source-compare-viewer.png)*Compare 2 to 6 sources with each other, similar to the Mirador web app.* + +--- + +### Annotate and connect your data (sources and/or metadata) +⚠ *NOT YET IMPLEMENTED* + +A main feature of the flexible data storage that DSP-APP uses is the possibility to annotate and link sources and their metadata. An annotation can be a small note about a date like "Not sure about the birthdate of this person. There's another date mentioned in the source XYZ". Inside the note, it will be possible to link to another source. + +Links in DSP-APP are always bi-directional. If you link source A with source B, then source B knows about this connection. If you find source B, you have the connection to source A as well. + +--- + +### Export, save or share the data +⚠ *NOT YET IMPLEMENTED* + +Data sets and metadata extracted through a search can be exported as CSV, XML, or other predefined file formats. +It will be also possible to store full text, advanced, and expert search queries to reuse them later, collect source objects in a collection similar to a playlist of a music app or a shopping basket. + +![The share menu offers many tools to export the data, to send it to someone or to store it in an individual source collection.](../assets/images/share-export-menu.png)*The share menu offers many tools to export the data, to send it to someone or to store it in an individual source collection.* diff --git a/docs/how-to-use/index.md b/docs/how-to-use/index.md new file mode 100644 index 0000000000..e101e2e88e --- /dev/null +++ b/docs/how-to-use/index.md @@ -0,0 +1,31 @@ +# User Guide + +This is the documentation for the generic Knora Web Application of the Data and Service Center for the Humanities DaSCH. You can reach the app on **[app2.dasch.swiss](https://app2.dasch.swiss)**. + +--- + +## Getting started + +DSP-APP is an intuitive, easy to use web-based application placed on top of [DSP-API](https://docs.dasch.swiss/developers/dsp-api/documentation/index.md) to directly use its powerful data management functionalities. With this modern web application, the researchers can create their data models, search, browse, and work with their qualitative data as easily as they could with a desktop data management tool. In addition, data models and data will automatically follow accepted standards, be interoperable, findable, and re-usable. Researchers and scholars with small to medium data sets (e.g. PhD research, pilot project, or proof of concept) have access to long-term accessibility to keep their research data alive, guaranteeing longevity of the data. + +--- + +## Login + +To login, click on the LOGIN button of the header (right side), a login form will appear. Fill in the form with your credentials (user name or email and password). + +![Get access to the login form.](../assets/images/dashboard-header.png) + +In case of a forgotten password, please contact the [DaSCH Team](https://dasch.swiss/team). + +--- + +## Registration + +You can use the DSP-APP with restricted access as guest. Otherwise, you'll need a login. At the moment, you have to contact the [DaSCH Team](https://dasch.swiss/team) to get your login credentials. In the future (end of 2020), we will support the [SWITCH edu-ID](https://www.switch.ch/edu-id/). + +--- + +## Help + +For any questions or help wanted, you can go to the help page, accessible from the Help button at the top right of the page (see [login screen shot](/user-guide/#login)). Here, you can find links to the user guide, get more information about the DaSCH softwares, and get more support through different platform according to your requests. diff --git a/docs/how-to-use/project.md b/docs/how-to-use/project.md new file mode 100644 index 0000000000..c553774f4b --- /dev/null +++ b/docs/how-to-use/project.md @@ -0,0 +1,111 @@ +# Project Administration + +## Project + +Once you are [logged in](/user-guide/#login), the dashboard displays the list of your project(s). If you are a project administrator or a system administrator, you can edit the project information or archive your project from the project menu. Archived projects are stored in a list on your dashboard and they can be "reactivated" at any time. + +![Project list and project menu](../assets/images/project-list.png)*https://app2.dasch.swiss/dashboard - By clicking on the project name, you get access to the full project information.* + +System administrator can create your new research project. Essential information are required such as the project name, a short project description and institution information. + +![Create a new project](../assets/images/project-create-new.png)
*Form to create a new project.*
+ +As project administrator or system administrator, you can define your project, add your team members, create permission groups and as most important, define your data model (ontology) and the lists of your project. + +![Project management available functionalities](../assets/images/project-info.png)*https://app2.dasch.swiss/project/0803/info - Project management functionalities; e.g. Incunabula project. Project information page is displayed without restricted content, the other functionalities are reserved for project admin and system admin.* + +--- + +## Collaboration +⚠ *WORK IN PROGRESS* + +As system admin, you can add users as project member and define their permissions roles: *Who is able to edit or to see data in the project?* Data includes the research sources and their metadata. [Permissions](/user-guide/project/#permission-groups) can be set for the entire project or for single metadata fields. + +A user menu with different actions is accessible for each member of the project (link to the right side of the user line). The admin can appoint another user as project admin (or remove this permission), edit user's information, change user's password if forgotten, and remove a user. + +![Collaboration page](../assets/images/project-collaboration.png)*https://app2.dasch.swiss/project/0803/collaboration - Collaboration page where project admin and system admin can add new user to the team.* + +***Permissions for project admins to add new users as project member will be implemented soon.*** + +--- + +## Permission groups +⚠ *NOT YET IMPLEMENTED* + +Project admin can create one or several permission groups in their project to set specific permissions on data to a user group. + +--- + +## Data model +⚠ *NOT YET IMPLEMENTED* (only mockups are presented) + +The most important step in the project is the definition of the data model. DSP-APP will provide a tool for easy creation of data models. First, you have to know which data and sources you want to work with. The data model can be flexible and customizable. With DSP-APP, you can comply with the FAIR data standard, but compliance is not required to analyze your data. + +The questions to answer in creating your data model: + +- *What kind of data do I have in my project?* +- *What are the sources and what are their metadata?* + +**For example:** You have interviewed 20 people. During these interviews that you recorded, you talked about photographs. Among all the data collected during the project, the most important are: + +- audio-files of the interview +- transcribed text of conversations (or transcribe the files within the web application) +- photographs +- data about the person you interviewed +- location where the photograph was taken + +Diagram 1 shows the relationships of the data by source type from these experiences. + +![Relationship of the data by source type](../assets/images/diagram-data-model.png)*Relationship of the data by source type* + +--- + +### Select your SOURCE TYPES + +In the data model editor, you select your source types from a predefined list on the right-hand side. Later, you will be able to customize the source type or define an additional default source type, if the one you need doesn't exist by default. + +![Data model editor 1: Select all your main source types by drag and drop; e.g. for an interview, select the source type "Audio / Sound / Interview".](../assets/images/data-model-add-source.png)*Data model editor 1: Select all your main source types by drag and drop; e.g. for an interview, select the source type "Audio / Sound / Interview".* + +In our example with the interview and the photographs, you drag and drop the following main source types from the list on the right-hand side: + +- Audio / Sound / Interview +- Transcript +- Image / Photograph / Postcard +- Person +- Location / Place + +--- + +### Select the METADATA fields for each source type (optional) + +The predefined source types offer a suggested list of metadata fields. This list could help to create a data model simply and quickly. It's also possible to deselect the suggested metadata fields (e.g., no metadata), to adapt others and to customize them. + +![Data model editor 2: Add additional metadata fields to your source type; e.g. add the missing field "Person".](../assets/images/data-model-add-property.png)*Data model editor 2: Add additional metadata fields to your source type; e.g. add the missing field "Person".* + +--- + +### Customize the SOURCE TYPES and the METADATA fields (optional) + +It's possible to customize the predefined source type and the metadata field values by clicking on the edit button of the source type. You can rename the source type, rearrange the order of the metadata fields, and set permissions. + +![Data model editor 3: Customize the source type AUDIO; e.g. rename it into Interview](../assets/images/data-model-edit-source.png)*Data model editor 3: Customize the source type AUDIO; e.g. rename it into Interview* + +--- + +### Connect SOURCE TYPES in the data model (optional) + +If you have reusable metadata value in a source type (A), you should create an additional source type (B) and drag-and-drop it over the metadata field of the first source type (A) to connect the two data types. +E.g., For the metadata "Photographer" in source type "Photograph", you should create a source type "Person" and connect it in "Photograph". + +![Data model editor 4: Manage connections between the source types.](../assets/images/data-model-example.png)*Data model editor 4: Manage connections between the source types.* + +---- + +## Lists +⚠ *WORK IN PROGRESS* + +Projects often need to define lists or hierarchies of categories that can be assigned to many different sources. Lists can be created by project admin and system admin. + +![Project lists](../assets/images/project-lists.png)*https://app2.dasch.swiss/project/0803/lists - Project lists: create a new list, add items by selecting the language and enter the corresponding value, repeat for each translation and press the + sign to create another item to the same level.* + +**The edition of items and child items will be implemented in a later version.** diff --git a/docs/how-to-use/publication.md b/docs/how-to-use/publication.md new file mode 100644 index 0000000000..e8ca526e48 --- /dev/null +++ b/docs/how-to-use/publication.md @@ -0,0 +1,3 @@ +# Publication + +⚠ *NOT YET IMPLEMENTED* \ No newline at end of file diff --git a/docs/how-to-use/system.md b/docs/how-to-use/system.md new file mode 100644 index 0000000000..a2cf06f206 --- /dev/null +++ b/docs/how-to-use/system.md @@ -0,0 +1,42 @@ +# System Administration + +⚠ Only for System administrator + +System administrators can get an overview of all projects and all users stored in Knora. + +![Get access to the system admin part from the user menu](../assets/images/system-user-menu.png)*System administration part is accessible from the user menu in the header.* + +--- + +## All projects + +System admin gets the list of all activated projects as well as archived projects. It is possible to create a new research project, the required information must be filled in. +For each project, the system admin has the possibility to edit the project information and archive the project. + +![Overview of all projects](../assets/images/system-all-projects.png)*Overview of all activated projects, the list of archived projects is displayed below.* + +--- + +## All users + +System admin gets the list of all activated and suspended users registered in Knora. +New users can be created from this page only (button "Create new"). + +![Overview of all users](../assets/images/system-all-users.png)*Overview of all users where the system admin has access to several actions.* + +For each user, the system admin has access to several actions: + +- *Add as system admin* or *Remove as system admin*: add or remove the user role of *system admin* + +- *Edit user*: edit the user information (e.g. first name, last name, default language) + +- *Change user's password*: the system admin can update the user's password if the user has forgotten it, the system admin must enter his password first (⚠ a reset password functionality will be implemented in a later version on the login page) + +![System admin can change user's password](../assets/images/system-change-user-pwd.png) + +- *Manage project membership*: the system admin can assign the selected user to one or several project, or remove the user from a specific project + +![System admin can add a user as a member user of a project](../assets/images/system-manage-project-membership.png) + +- *Suspend user*: the user is deactivated and has no more access to DSP-APP. The system admin can reactivate it at any time. + diff --git a/docs/how-to-use/user.md b/docs/how-to-use/user.md new file mode 100644 index 0000000000..7ae23ddd41 --- /dev/null +++ b/docs/how-to-use/user.md @@ -0,0 +1,34 @@ +# User Administration + +![Get access to your user profile and more](../assets/images/usermenu-to-userprofile.png)*https://app2.dasch.swiss/dashboard - Get access to your user profile, collections and account from the main user menu.* + +--- + +## Your user profile and projects + +To change your personal information as well as your default language used by the interface, you can edit your profile clicking *Edit*. Currently, the avatar image comes from gravatar.com (go on their [website](http://en.gravatar.com/) to register if you want your customized user photo). + +![Get access to your user profile and more](../assets/images/user-profile.png)*https://app2.dasch.swiss/projects - Overview of your user profile and your projects.* + +The list of your projects is accessible, click on one project to get more information about it. As project admin, you can also edit or archive your projects, and as system admin, you can additionally create new project on this page. + +![Edit user's profile](../assets/images/user-edit-profile.png)*Edit your user profile. The username, the email address and the admin rules are not editable.* + +--- + +## Your collections + +⚠ *NOT YET IMPLEMENTED* + +You will be able to store collections of sources or specific searches to work with them later or share them with collaborators. + +--- + +## Your account + +As a matter of security, it is strongly recommended to update your password at least once a year. In your account page, you can update your password. + +![Get access to the user account where the user can reset its password and deactivate its own account](../assets/images/user-account.png)*https://app2.test.dasch.swiss/account - Update your password and deactivate your user account.* + +⚠ +You can delete (deactivate) your own user account. Only a system administrator will be able to reactivate it. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000000..4129e67ee0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% + include-markdown "../README.md" +%} diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000..7d42063de6 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,4 @@ +mkdocs==1.1.2 +mkdocs-material==6.0.1 +mkdocs-include-markdown-plugin==2.7.1 +mkdocs-git-revision-date-plugin==0.3.1 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000000..6b969cc112 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,41 @@ +site_name: DSP-APP documentation + +repo_url: https://github.com/dasch-swiss/dsp-app +repo_name: dasch-swiss/dsp-app +edit_uri: blob/main/docs/ +copyright: "© 2017 - 2021 Data and Service Center for the Humanities (DaSCH)" + +nav: + - Introduction: index.md + - User Guide: + - Introduction: how-to-use/index.md + - Project Administration: how-to-use/project.md + - User Administration: how-to-use/user.md + - System Administration: how-to-use/system.md + # - Data Management: how-to-use/data.md + # - Publication: how-to-use/publication.md + - Contribution: + - How to contribute: how-to-contribute/index.md + - Docs Documentation: how-to-contribute/docs-documentation.md + - Release Notes: how-to-contribute/release-notes.md + +plugins: + - include-markdown + - search + - git-revision-date + +theme: + name: material + logo: 'assets/icons/dasch-icon-white.svg' + favicon: 'assets/icons/dasch-favicon.ico' + icon: + repo: fontawesome/brands/github + palette: + primary: 'deep purple' + accent: 'deep purple' + features: + - navigation.tabs + - navigation.sections + +extra_css: + - 'assets/style/theme.css'