Skip to content
Permalink
Browse files
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
  • Loading branch information
kilchenmann committed Feb 12, 2021
1 parent 5b6ee4b commit 07f50678c75d1da4cfc2c4792917b13840b5eaf6
Showing with 2,228 additions and 37 deletions.
  1. +50 −0 .github/workflows/main.yml
  2. +27 −0 Makefile
  3. +15 −37 README.md
  4. +89 −0 docs/README.md
  5. BIN docs/assets/fonts/roboto-v19-latin-300.eot
  6. +312 −0 docs/assets/fonts/roboto-v19-latin-300.svg
  7. BIN docs/assets/fonts/roboto-v19-latin-300.ttf
  8. BIN docs/assets/fonts/roboto-v19-latin-300.woff
  9. BIN docs/assets/fonts/roboto-v19-latin-300.woff2
  10. BIN docs/assets/fonts/roboto-v19-latin-500.eot
  11. +305 −0 docs/assets/fonts/roboto-v19-latin-500.svg
  12. BIN docs/assets/fonts/roboto-v19-latin-500.ttf
  13. BIN docs/assets/fonts/roboto-v19-latin-500.woff
  14. BIN docs/assets/fonts/roboto-v19-latin-500.woff2
  15. BIN docs/assets/fonts/roboto-v19-latin-700.eot
  16. +309 −0 docs/assets/fonts/roboto-v19-latin-700.svg
  17. BIN docs/assets/fonts/roboto-v19-latin-700.ttf
  18. BIN docs/assets/fonts/roboto-v19-latin-700.woff
  19. BIN docs/assets/fonts/roboto-v19-latin-700.woff2
  20. BIN docs/assets/fonts/roboto-v19-latin-italic.eot
  21. +323 −0 docs/assets/fonts/roboto-v19-latin-italic.svg
  22. BIN docs/assets/fonts/roboto-v19-latin-italic.ttf
  23. BIN docs/assets/fonts/roboto-v19-latin-italic.woff
  24. BIN docs/assets/fonts/roboto-v19-latin-italic.woff2
  25. BIN docs/assets/fonts/roboto-v19-latin-regular.eot
  26. +308 −0 docs/assets/fonts/roboto-v19-latin-regular.svg
  27. BIN docs/assets/fonts/roboto-v19-latin-regular.ttf
  28. BIN docs/assets/fonts/roboto-v19-latin-regular.woff
  29. BIN docs/assets/fonts/roboto-v19-latin-regular.woff2
  30. BIN docs/assets/icons/dasch-favicon.ico
  31. +8 −0 docs/assets/icons/dasch-icon-white.svg
  32. BIN docs/assets/icons/favicon.png
  33. BIN docs/assets/images/dasch-favicon.ico
  34. +8 −0 docs/assets/images/dasch-icon-white.svg
  35. BIN docs/assets/images/dashboard-header.png
  36. BIN docs/assets/images/data-model-add-property.png
  37. BIN docs/assets/images/data-model-add-source.png
  38. BIN docs/assets/images/data-model-edit-source.png
  39. BIN docs/assets/images/data-model-example.png
  40. BIN docs/assets/images/data-model-init.png
  41. BIN docs/assets/images/diagram-data-model.png
  42. BIN docs/assets/images/favicon.png
  43. BIN docs/assets/images/material-mat-display-titles.png
  44. BIN docs/assets/images/material-typography.png
  45. BIN docs/assets/images/mock-source-new-edit.png
  46. BIN docs/assets/images/project-collaboration.png
  47. BIN docs/assets/images/project-create-new.png
  48. BIN docs/assets/images/project-info.png
  49. BIN docs/assets/images/project-list.png
  50. BIN docs/assets/images/project-lists.png
  51. BIN docs/assets/images/resource-view-with-image.png
  52. BIN docs/assets/images/search-3modes.png
  53. BIN docs/assets/images/search-advanced-diagram.png
  54. BIN docs/assets/images/search-advanced-link.png
  55. BIN docs/assets/images/search-advanced-mockup.png
  56. BIN docs/assets/images/search-advanced.png
  57. BIN docs/assets/images/search-expert-gravsearch-mockup.png
  58. BIN docs/assets/images/search-expert-link.png
  59. BIN docs/assets/images/search-expert.png
  60. BIN docs/assets/images/search-fulltext-filterByProject.png
  61. BIN docs/assets/images/search-history.png
  62. BIN docs/assets/images/search-results-grid-list-mockup.png
  63. BIN docs/assets/images/search-results-grid.png
  64. BIN docs/assets/images/search-results-list.png
  65. BIN docs/assets/images/search-results-simple-list-mockup.png
  66. BIN docs/assets/images/search-results-table-mockup.png
  67. +1 −0 docs/assets/images/search.svg
  68. BIN docs/assets/images/share-export-menu.png
  69. BIN docs/assets/images/source-compare-viewer.png
  70. BIN docs/assets/images/source-form.png
  71. BIN docs/assets/images/source-graph-view.png
  72. BIN docs/assets/images/source-selected-fullframe.png
  73. BIN docs/assets/images/source-selected-one.png
  74. BIN docs/assets/images/source-selected-three.png
  75. BIN docs/assets/images/system-all-projects.png
  76. BIN docs/assets/images/system-all-users.png
  77. BIN docs/assets/images/system-change-user-pwd.png
  78. BIN docs/assets/images/system-manage-project-membership.png
  79. BIN docs/assets/images/system-user-menu.png
  80. BIN docs/assets/images/user-account.png
  81. BIN docs/assets/images/user-edit-profile.png
  82. BIN docs/assets/images/user-profile.png
  83. BIN docs/assets/images/usermenu-to-userprofile.png
  84. +4 −0 docs/assets/style/theme.css
  85. +3 −0 docs/how-to-contribute/docs-documentation.md
  86. +27 −0 docs/how-to-contribute/index.md
  87. +3 −0 docs/how-to-contribute/release-notes.md
  88. +167 −0 docs/how-to-use/data.md
  89. +31 −0 docs/how-to-use/index.md
  90. +111 −0 docs/how-to-use/project.md
  91. +3 −0 docs/how-to-use/publication.md
  92. +42 −0 docs/how-to-use/system.md
  93. +34 −0 docs/how-to-use/user.md
  94. +3 −0 docs/index.md
  95. +4 −0 docs/requirements.txt
  96. +41 −0 mkdocs.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
@@ -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) .
@@ -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).
@@ -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!
Binary file not shown.
Loading

0 comments on commit 07f5067

Please sign in to comment.