Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
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 603efef
Show file tree
Hide file tree
Showing 83 changed files with 278 additions and 7,539 deletions.
2 changes: 1 addition & 1 deletion .github/workflows/main.yml
Expand Up @@ -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:
Expand Down
4 changes: 4 additions & 0 deletions .gitignore
Expand Up @@ -44,3 +44,7 @@ dependencies.txt
metals.sbt

.tmp/

# exclude python virtual environments used for serving docs locally
env/
venv/
26 changes: 5 additions & 21 deletions 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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand All @@ -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.
Expand Down Expand Up @@ -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!
32 changes: 16 additions & 16 deletions docs/03-apis/api-v1/reading-and-searching-resources.md
Expand Up @@ -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:

Expand Down Expand Up @@ -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.

```
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/03-apis/api-v2/query-language.md
Expand Up @@ -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`.
Expand Down
4 changes: 2 additions & 2 deletions docs/03-apis/api-v2/reading-and-searching-resources.md
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions docs/05-internals/development/building-and-running.md
Expand Up @@ -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:
Expand Down
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file removed docs/05-internals/development/figures/sbt-config.png
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Binary file not shown.
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.
85 changes: 0 additions & 85 deletions docs/05-internals/development/graphdb.md

This file was deleted.

4 changes: 1 addition & 3 deletions docs/05-internals/development/index.md
Expand Up @@ -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)
68 changes: 0 additions & 68 deletions docs/05-internals/development/intellij-config.md

This file was deleted.

8 changes: 0 additions & 8 deletions docs/05-internals/development/migrationNotes.md

This file was deleted.

15 changes: 1 addition & 14 deletions docs/05-internals/development/overview.md
Expand Up @@ -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

Expand Down

0 comments on commit 603efef

Please sign in to comment.