docs: init mkdocs and move documentation from DSP-DOCS into DSP-APP r…

…epo (DSP-380) (#379)

* docs: init mkdocs

* docs: move content from dsp-docs to docs folder

* chore(gh-ci): test and publish documentation

* chore(gh-ci): test docs deployment

* chore(gh-ci): undo docs deploy test

* docs: update and add docs documentation

* docs(contribution): add release notes

* docs(user-guide): clean up structure

.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

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) .

README.md

@@ -8,64 +8,42 @@
 
 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.
 
 Please check our [DSP Release Compatibility Matrix](https://docs.google.com/spreadsheets/d/e/2PACX-1vQe-0nFKqYHwHT3cNI2M_ZCycKOgDZBxtaabxEQDDkNKJf6funMVrJBJPgMFEJdiBdCesahUhURN6MS/pubhtml) to use this app with the correct and required versions of the dependent packages.
 
 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 <https://github.com/dasch-swiss/dsp-app/releases> 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 <https://hub.docker.com/repository/docker/daschswiss/dsp-app>.
+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).

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 (<https://docs.dasch.swiss/developers/dsp/contribution/>)
+    - 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 <http://127.0.0.1:8000/> 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!