Skip to content
Permalink
Browse files
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
  • Loading branch information
BalduinLandolt committed Apr 5, 2022
1 parent 470b77f commit 603efeffa35204dcbe59554f4ba33cc58c1e66ae
Showing with 278 additions and 7,539 deletions.
  1. +1 −1 .github/workflows/main.yml
  2. +4 −0 .gitignore
  3. +5 −21 README.md
  4. +16 −16 docs/03-apis/api-v1/reading-and-searching-resources.md
  5. +1 −1 docs/03-apis/api-v2/query-language.md
  6. +2 −2 docs/03-apis/api-v2/reading-and-searching-resources.md
  7. +6 −0 docs/05-internals/development/building-and-running.md
  8. BIN docs/05-internals/development/figures/bazel-UncommentScala.png
  9. BIN docs/05-internals/development/figures/bazel-buildFile.png
  10. BIN docs/05-internals/development/figures/bazel-command-config.png
  11. BIN docs/05-internals/development/figures/bazel-config-setup.png
  12. BIN docs/05-internals/development/figures/bazel-debug.png
  13. BIN docs/05-internals/development/figures/bazel-new-config.png
  14. BIN docs/05-internals/development/figures/bazel-run-config.png
  15. BIN docs/05-internals/development/figures/bazel-sync.png
  16. BIN docs/05-internals/development/figures/bazel-workspace.png
  17. BIN docs/05-internals/development/figures/import-from-sbt.png
  18. BIN docs/05-internals/development/figures/install-scala-plugin.png
  19. BIN docs/05-internals/development/figures/intellij-after-import.png
  20. BIN docs/05-internals/development/figures/launch-visualvm.png
  21. BIN docs/05-internals/development/figures/sbt-config.png
  22. BIN docs/05-internals/development/figures/setup_formatting.png
  23. BIN docs/05-internals/development/figures/visualvm-call-tree.png
  24. BIN docs/05-internals/development/figures/visualvm-overview.png
  25. BIN docs/05-internals/development/figures/visualvm-sampler.png
  26. BIN docs/05-internals/development/figures/visualvm-snapshot-button.png
  27. BIN docs/05-internals/development/figures/visualvm-snapshot.png
  28. BIN docs/05-internals/development/figures/vscode-docker.png
  29. BIN docs/05-internals/development/figures/vscode-metals-test-codelens.png
  30. BIN docs/05-internals/development/figures/vscode-metals-test.png
  31. +0 −85 docs/05-internals/development/graphdb.md
  32. +1 −3 docs/05-internals/development/index.md
  33. +0 −68 docs/05-internals/development/intellij-config.md
  34. +0 −8 docs/05-internals/development/migrationNotes.md
  35. +1 −14 docs/05-internals/development/overview.md
  36. +0 −23 docs/05-internals/development/profiling.md
  37. +44 −9 docs/05-internals/development/third-party.md
  38. +37 −0 docs/05-internals/development/vscode-config.md
  39. 0 docs/{07-sipi → 06-sipi}/index.md
  40. 0 docs/{07-sipi → 06-sipi}/setup-sipi-for-dsp-api.md
  41. 0 docs/{07-sipi → 06-sipi}/sipi-and-dsp-api.md
  42. 0 docs/{08-lucene → 07-lucene}/index.md
  43. 0 docs/{08-lucene → 07-lucene}/lucene-query-parser-syntax.md
  44. +0 −31 docs/Makefile
  45. +2 −2 docs/index.md
  46. +24 −3 docs/requirements.txt
  47. +0 −29 docs/src/api-admin/index.html
  48. +0 −160 docs/src/api-v1/addValueFormats.ts
  49. +0 −454 docs/src/api-v1/basicMessageComponents.ts
  50. +0 −195 docs/src/api-v1/changeValueFormats.ts
  51. +0 −226 docs/src/api-v1/createResourceFormats.ts
  52. +0 −43 docs/src/api-v1/deleteResponseFormats.ts
  53. +0 −78 docs/src/api-v1/graphDataResponseFormats.ts
  54. +0 −158 docs/src/api-v1/groupFormats.ts
  55. +0 −100 docs/src/api-v1/hierarchicalListResponseFormats.ts
  56. +0 −56 docs/src/api-v1/mappingFormats.ts
  57. +0 −161 docs/src/api-v1/permissionFormats.ts
  58. +0 −252 docs/src/api-v1/projectFormats.ts
  59. +0 −760 docs/src/api-v1/resourceResponseFormats.ts
  60. +0 −19 docs/src/api-v1/sampleRequests/sampleAddValues.ts
  61. +0 −18 docs/src/api-v1/sampleRequests/sampleChangeValues.ts
  62. +0 −48 docs/src/api-v1/sampleRequests/sampleCreateResources.ts
  63. +0 −10 docs/src/api-v1/sampleRequests/sampleDeleteResponses.ts
  64. +0 −8 docs/src/api-v1/sampleRequests/sampleGraphDataResponse.ts
  65. +0 −19 docs/src/api-v1/sampleRequests/sampleHierarchicalList.ts
  66. +0 −126 docs/src/api-v1/sampleRequests/sampleLoginResponse.ts
  67. +0 −86 docs/src/api-v1/sampleRequests/sampleResourceResponses.ts
  68. +0 −18 docs/src/api-v1/sampleRequests/sampleValueResponse.ts
  69. +0 −127 docs/src/api-v1/searchResponseFormats.ts
  70. +0 −34 docs/src/api-v1/sessionResponseFormats.ts
  71. +0 −264 docs/src/api-v1/userFormats.ts
  72. +0 −169 docs/src/api-v1/valueResponseFormats.ts
  73. +0 −41 docs/src/api-v2/Basic.ts
  74. +0 −104 docs/src/api-v2/ListResponse.ts
  75. +0 −67 docs/src/api-v2/MappingFormats.ts
  76. +0 −146 docs/src/api-v2/ResourcesResponse.ts
  77. +0 −75 docs/src/api-v2/samples/listResponses.ts
  78. +0 −22 docs/src/api-v2/samples/mappingMessages.ts
  79. +0 −2,987 docs/src/api-v2/samples/resourcesResponses.ts
  80. +134 −138 mkdocs.yml
  81. +0 −11 test_data/demo_data/image-collection-demo-data-description.md
  82. +0 −10 test_data/demo_data/incunabula-demo-data-description.md
  83. +0 −33 test_data/project_shortcodes.md
@@ -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:
@@ -44,3 +44,7 @@ dependencies.txt
metals.sbt

.tmp/

# exclude python virtual environments used for serving docs locally
env/
venv/
@@ -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!
@@ -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.
@@ -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`.
@@ -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
@@ -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:
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

This file was deleted.

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

This file was deleted.

This file was deleted.

@@ -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

0 comments on commit 603efef

Please sign in to comment.