docs: replace Bazel and Intellij documentation with SBT and VSCode (D…

…EV-607) (#2035)

* docs: start working on documentation

* Update README.md

* chore: update mkdocs-related stuff

* docs: cleanup

* docs: more cleanup

* docs: more tidy up

* docs: start documenting vscode

* docs: document vscode

* docs: remove unused images

* docs: remove typedoc

* docs: update docs makefile

* docs: document third party library usage

* fix syntax in main.yml

* docs: update docs according to review comments

* docs: update file path numbering

* docs: changes according to review

.github/workflows/main.yml

@@ -187,7 +187,7 @@ jobs:
             {"type": "chore", "section": "Maintenance", "hidden": false },
             {"type": "refactor", "section": "Maintenance", "hidden": false },
             {"type": "docs", "section": "Documentation", "hidden": false }
-          ]'
+            ]'
 
   # publish only on release
   publish:

.gitignore

@@ -44,3 +44,7 @@ dependencies.txt
 metals.sbt
 
 .tmp/
+
+# exclude python virtual environments used for serving docs locally
+env/
+venv/

README.md

@@ -1,17 +1,17 @@
-# Knora — Knowledge Organization, Representation, and Annotation
+# DSP-API — DaSCH Service Platform API
 
 [![Github](https://img.shields.io/github/v/tag/dasch-swiss/dsp-api?include_prereleases&label=Github%20tag)](https://github.com/dasch-swiss/dsp-api)
 [![Docker](https://img.shields.io/docker/v/daschswiss/knora-api?label=Docker%20image)](https://hub.docker.com/r/daschswiss/knora-api)
 [![CI](https://github.com/dasch-swiss/dsp-app/workflows/CI/badge.svg)](https://github.com/dasch-swiss/dsp-api/actions?query=workflow%3ACI)
 
-[Knora](https://www.knora.org/) is a server application for storing, sharing, and working with primary sources and data in the humanities.
+[DSP](https://admin.dasch.swiss/) is a server application for storing, sharing, and working with primary sources and data in the humanities.
 
 It is developed by the [Swiss National Data and Service Center for the Humanities](https://dasch.swiss)
 at the [University of Basel](https://www.unibas.ch), and is supported by the
 [Swiss Academy of Humanities and Social Sciences](https://www.sagw.ch) and
 the [Swiss National Science Foundation](https://snf.ch).
 
-Knora is [free software](http://www.gnu.org/philosophy/free-sw.en.html),
+DSP-API is [free software](http://www.gnu.org/philosophy/free-sw.en.html),
 released under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
 
 ## Features
@@ -39,10 +39,6 @@ released under the [Apache License, Version 2.0](http://www.apache.org/licenses/
 * [Knora Admin API](https://docs.knora.org/03-apis/api-admin/)
 * Distribution packaging using [Docker](https://www.docker.com/)
 
-### New features under development
-
-* See the [Roadmap](https://github.com/dasch-swiss/knora-api/wiki/Roadmap)
-
 ## Requirements
 
 ### For developing and testing the API server
@@ -129,7 +125,7 @@ implementing the desired functionality.
 
 Use `camelCase` for names of classes, variables, and functions. Make names descriptive, and don't worry if they're long.
 
-Use [Scalafmt](https://scalameta.org/scalafmt/) in [IntelliJ IDEA](https://www.jetbrains.com/idea) to format Scala code.
+Use [Scalafmt](https://scalameta.org/scalafmt/) in Visual Studio Code to format Scala code.
 
 Use whitespace to make your code easier to read.
 Add lots of implementation comments describing what your code is doing,
@@ -143,7 +139,6 @@ There are three sets of automated tests:
 
 * Unit tests, route-to-route tests, and end-to-end tests are under `webapi/src/test`. To run these, type `graphdb:test` or `graphdb-free:test` (depending on which triplestore you're using) at the SBT console in the `webapi` project. To run a single test, use `graphdb:test-only *NameOfTestSpec`.
 * Integration tests, which can involve [Sipi](https://github.com/daschswiss/sipi), are under `src/it`. To run these, first start Sipi, then type `it:test` at the SBT console in the `webapi` project.
-* Browser interaction tests are under `salsah/src/test`, and are written using [Selenium](https://www.seleniumhq.org). To run these, you will need to unpack the correct [ChromeDriver](https://sites.google.com/a/chromium.org/chromedriver/) for your platform found under `salsah/lib/chromedriver` and put it in the same folder. Then start Sipi and the Knora API server, and type `test` at the SBT console in the `salsah` project.
 
 Whenever you add a new feature or fix a bug, you should add one or more tests
 for the change you made.
@@ -175,15 +170,4 @@ data would be necessary, e.g., any changes to the Knora-Base ontologies which ar
 
 ## Release Notes Generation
 
-A pull request usually resolves one issue or user story defined on [Youtrack](https://dasch.myjetbrains.com/youtrack/). Since we started to use the [release-please-action](https://github.com/marketplace/actions/release-please-action) it's very important to set the PR title in the correct way, especially becuase all commits added within the pull request are squashed. Please read the official [DSP Contribution Documentation](https://docs.dasch.swiss/developers/dsp/contribution/#pull-request-guidelines) carefully!
-
-## Acknowledgments
-
-![YourKit](https://www.yourkit.com/images/yklogo.png)
-
-The Knora project is using YourKit for profiling.
-
-YourKit supports open source projects with its full-featured Java Profiler.
-YourKit, LLC is the creator of [YourKit Java Profiler](https://www.yourkit.com/java/profiler/)
-and [YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/),
-innovative and intelligent tools for profiling Java and .NET applications.
+A pull request usually resolves one issue or user story defined on [Jira](https://dasch.atlassian.net/browse/DEV). Since we started to use the [release-please-action](https://github.com/marketplace/actions/release-please-action) it's very important to set the PR title in the correct way, especially because all commits added within the pull request are squashed. Please read the official [DSP Contribution Documentation](https://docs.dasch.swiss/developers/dsp/contribution/#pull-request-guidelines) carefully!

docs/03-apis/api-v1/reading-and-searching-resources.md

@@ -189,7 +189,7 @@ interface `vocabularyResponse` in module `resourceResponseFormats`.
 This is a simplified way for searching for resources just by their label. 
 Search by label automatically adds Lucene operators, 
 search strings are expected not to contain any characters with a special meaning in 
-[Lucene Query Parser syntax](../../08-lucene/index.md).
+[Lucene Query Parser syntax](../../07-lucene/index.md).
 
 It is a simple string-based method:
 
@@ -221,7 +221,7 @@ TypeScript interface `resourceLabelSearchResponse` in module
 
 Knora offers a fulltext search that searches through all textual
 representations of values. The search terms have to be URL encoded.
-Fulltext search supports the [Lucene Query Parser syntax](../../08-lucene/index.md).
+Fulltext search supports the [Lucene Query Parser syntax](../../07-lucene/index.md).
 Note that Lucene's default operator is a logical OR when submitting several search terms.
 
 ```
@@ -280,19 +280,19 @@ The following table indicates the possible combinations of value types
 and comparison
 operators:
 
-| Value Type       | Comparison Operator                                   |
-| ---------------- | ----------------------------------------------------- |
-| Date Value       | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS                 |
-| Integer Value    | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS                 |
-| Float Value      | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS                 |
-| Text Value       | MATCH_BOOLEAN, MATCH, EQ, !EQ, LIKE, !LIKE, EXISTS    |
-| Geometry Value   | EXISTS                                                |
-| Geoname Value    | EQ, EXISTS                                            |
-| URI Value        | EQ, EXISTS                                            |
-| Resource Pointer | EQ, EXISTS                                            |
-| Color Value      | EQ, EXISTS                                            |
-| List Value       | EQ, EXISTS                                            |
-| Boolean Value    | EQ, !EQ, EXISTS                                       |
+| Value Type       | Comparison Operator                                |
+| ---------------- | -------------------------------------------------- |
+| Date Value       | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS              |
+| Integer Value    | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS              |
+| Float Value      | EQ, !EQ, GT, GT_EQ, LT, LT_EQ, EXISTS              |
+| Text Value       | MATCH_BOOLEAN, MATCH, EQ, !EQ, LIKE, !LIKE, EXISTS |
+| Geometry Value   | EXISTS                                             |
+| Geoname Value    | EQ, EXISTS                                         |
+| URI Value        | EQ, EXISTS                                         |
+| Resource Pointer | EQ, EXISTS                                         |
+| Color Value      | EQ, EXISTS                                         |
+| List Value       | EQ, EXISTS                                         |
+| Boolean Value    | EQ, !EQ, EXISTS                                    |
 
 Explanation of the comparison operators:
 
@@ -330,7 +330,7 @@ Explanation of the comparison operators:
   value when using EXISTS: "searchval="**. Otherwise, the query
   syntax rules would be violated.
 * `MATCH`: checks if a resource's text value *matches* the search
-  value, see [Lucene Query Parser Syntax](../../08-lucene/lucene-query-parser-syntax.md).
+  value, see [Lucene Query Parser Syntax](../../07-lucene/lucene-query-parser-syntax.md).
 * `LIKE`: checks if the search value is contained in a resource's
   text value using the SPARQL [REGEX](https://www.w3.org/TR/sparql11-query/#func-regex) function,
   thus supporting regular expressions.

docs/03-apis/api-v2/query-language.md

@@ -380,7 +380,7 @@ The first argument must represent a text value (a `knore-api:TextValue` in
 the complex schema, or an `xsd:string` in the simple schema). The second
 argument is a string literal containing the words to be matched, separated by spaces.
 The function supports the
-[Lucene Query Parser syntax](../../08-lucene/index.md).
+[Lucene Query Parser syntax](../../07-lucene/index.md).
 Note that Lucene's default operator is a logical OR when submitting several search terms.
 
 This function can only be used as the top-level expression in a `FILTER`.

docs/03-apis/api-v2/reading-and-searching-resources.md

@@ -467,7 +467,7 @@ make this kind of "search as you type" possible, a wildcard character is
 automatically added to the last search term. 
 Search by label automatically adds Lucene operators, 
 search strings are expected not to contain any characters with a special meaning in 
-[Lucene Query Parser syntax](../../08-lucene/index.md).
+[Lucene Query Parser syntax](../../07-lucene/index.md).
 
 ```
 HTTP GET to http://host/v2/searchbylabel/searchValue[limitToResourceClass=resourceClassIRI]
@@ -499,7 +499,7 @@ The response to a count query request is an object with one predicate,
 Knora offers a full-text search that searches through all textual
 representations of values and `rdfs:label` of resources. 
 Full-text search supports the 
-[Lucene Query Parser syntax](../../08-lucene/index.md).
+[Lucene Query Parser syntax](../../07-lucene/index.md).
 Note that Lucene's default operator is a logical OR when submitting several search terms.
 
 Please note that the search

docs/05-internals/development/building-and-running.md

@@ -103,6 +103,12 @@ Lastly, to print out the entire logs of the running knora-stack, use
 $ make stack-logs
 ```
 
+With the Docker plugin installed, you can attach a terminal to the docker container within VS Code. This will stream the docker logs to the terminal window of the editor.
+
+![screenshot 'VSCode Docker'](figures/vscode-docker.png)
+
+The docker plugin also allows for a number of other useful features, like inspecting the container's file system or attaching a shell to the container.
+
 ## Running the automated tests
 
 To run all test targets, use the following in the command line:

docs/05-internals/development/index.md

@@ -6,13 +6,11 @@
 # Development
 
 - [Overview](overview.md)
-- [Starting GraphDB](graphdb.md)
 - [Build and Running](building-and-running.md)
-- [Setup IntelliJ for development of Knora](intellij-config.md)
+- [Setup Visual Studio Code for development of Knora](vscode-config.md)
 - [Testing](testing.md)
 - [Docker Cheat Sheet](docker-cheat-sheet.md)
 - [Monitoring Knora](monitoring.md)
-- [Profiling Knora](profiling.md)
 - [Starting the Knora Stack inside Docker Container](docker-compose.md)
 - [Updating Repositories](updating-repositories.md)
 - [Generating Client Test Data](generating-client-test-data.md)

docs/05-internals/development/overview.md

@@ -25,20 +25,7 @@ installation of Knora. The different parts are:
 A number of triplestore implementations are available, including [free
 software](http://www.gnu.org/philosophy/free-sw.en.html) as well as
 proprietary options. DSP-API is designed to work with any
-standards-compliant triplestore. It is primarily tested with [Ontotext
-GraphDB](http://ontotext.com/products/graphdb/), a high-performance,
-proprietary triplestore. We recommend GraphDB Standard Edition, but
-GraphDB Free (which is proprietary but available free of charge) also
-works.
-
-DSP-API includes support for [Apache Jena](https://jena.apache.org/),
-which is [free software](http://www.gnu.org/philosophy/free-sw.en.html),
-but use of Jena is deprecated, and support for it will probably be
-removed in the future.
-
-Built-in support and configuration for other triplestores is planned.
-
-See the chapter on [Starting GraphDB](graphdb.md) for more details.
+standards-compliant triplestore. It is primarily tested with [Apache Jena](https://jena.apache.org/).
 
 ## Sipi