Improve Docs #264

tobiasschweizer · 2020-11-25T13:20:24Z

This PR reorganises the docs:

README.md (project root): brief introduction to DSP-JS-LIB and shows how to use it
contribution.md: information for developers
design-documentation.md: design and architecture
test-framework/README.md: how to run the test Angular app and how to run E2E test

The API docs have been improved and can be generated locally by running npm run builddocs.
This PR adds the @category tag to classes, interfaces, and namespaces so that the API docs are organised by different sections:

"Config"
"Response"
"Endpoint Admin"
"Endpoint V2"
"Endpoint System"
"Model Admin"
"Model V2"
"Model System"
"Internal"

It would be nice to exclude the "Internal" category for the published API docs. I requested this feature.

tobiasschweizer · 2020-12-02T10:23:55Z

Also not sure if this is anywhere mentioned, to run e2e tests in test-framework, DSP-API needs to be restarted every time before with volume deletion. Is this correct?

In test-framework/README.md, I added the sentence:

Make sure that DSP-API's database is in its initial state. Reload the data if necessary.

I think the details how to do this should be covered by the DSP-API docs. I usually delete all the volumes. I believe there is a problem with stopping the db container.

mpro7

So what are we doing with links? Is it better to link at all or do not link to do not mess up with versions? I would link - here is why.

README.md

mpro7 · 2020-12-02T10:42:54Z

README.md

-For the public API, see <https://dasch-swiss.github.io/dsp-js-lib>.
-For design documentation, see file `design-documentation.md`.
+## Developing DSP-JS-LIB
+See `contribution.md`.


That was my point of every comment suggesting the link. Linking makes life way easier. One just can click to open in external tab and keep read the docs.

contribution.md

test-framework/README.md

tobiasschweizer · 2020-12-02T13:18:03Z

So what are we doing with links? Is it better to link at all or do not link to do not mess up with versions? I would link - here is why.

Could we try to find a general solution for this? Other repos will need that too and it should be handled in a consistent manner so all fits together in the end. How about tomorrow after the meeting?

mpro7

From my side it looks ok now. So we can move the links topic to another task, talking about it first, like suggested.

tobiasschweizer · 2020-12-02T13:34:53Z

From my side it looks ok now. So we can move the links topic to another task, talking about it first, like suggested.

Shall I schedule a meeting for tomorrow?

mdelez

Making our docs great again!

mdelez · 2020-12-02T15:50:15Z

README.md


-Below you may find a minimal example in TypeScript for the process of the user login.
+Make sure that `rxjs` is installed in the required major version 6 with the framework you are using, e.g. Angular.


"Make sure that your version of 'rxjs' is major version 6 with..."

done in 12cd1f1

mdelez · 2020-12-02T15:50:40Z

README.md


-We recommend to install this library through NPM. This will make sure that all dependencies are installed.
-At the moment, this library depends on `rxjs`, `json2typescript`, and `jsonld`.
+Consult the API docs for more details about the available endpoints..


You have two periods here

done in 12cd1f1

mdelez · 2020-12-02T15:52:31Z

README.md

+    console.log(res);
+  },
+  (error) => {
+    // for some reason, the request failed


"if, for some reason, the request failed"

done in 12cd1f1

mdelez · 2020-12-02T15:53:36Z

contribution.md

+
+## Introduction
+
+The purpose of this library is facilitating the use of [DSP-API (Knora)](https://www.knora.org) in web client development. 


"The purpose of this library is to facilitate the use of..."

done in 8a12b84

mdelez · 2020-12-02T15:54:59Z

contribution.md

+
+1. `npm run peer-deps`: Installs the project's peer dependencies. Peer dependencies are not installed with `npm install`, but have to be met before building or running the tests.
+1. `npm run test`: Runs the library's tests defined in `./karma.conf.js`.
+1. `npm run prepare-dev-publication`: prepares a dev version of the library **before** building it. The dev version contains code to create mocked data to be used in unit test of projects using DSP-JS-LIB.


"unit test" should be plural

done in 8a12b84

mdelez · 2020-12-03T09:09:11Z

design-documentation.md


+DSP-API System endpoints inform about DSP-API's status.


Not exactly sure what this is trying to say, perhaps "DSP-API System endpoints provide information about DSP-API's status."?

done in cc70b8e

mdelez · 2020-12-03T09:10:05Z

design-documentation.md


-The Knora Admin API is used to administrate projects in Knora. This also includes management of users and groups as well as permissions.
-The Knora API relies on JSON as an exchange format.
+The `HealthEndpointSystem` returns DSP-API's health status including information about the is version.


"about the version"

done in cc70b8e

mdelez · 2020-12-03T09:17:34Z

design-documentation.md


 `ResourcesConversionUtil` handles the conversion of one or several resources serialized as JSON-LD to an array of `ReadResource`. 
 `ResourcesConversionUtil` creates an array of `ReadResource` from JSON-LD representing resource instances, 
 automatically adding ontology information such as resource class labels and labels from list nodes that are referred to from list values.
-It does so by using `OntologyCache` and `ListNodeCache`, minimizing the requests to the Knora API to obtain the necessary information.
+It does so by using `OntologyCache` and `ListNodeCache`, minimizing the requests to DSP-API to obtain the necessary information.

 `ResourcesConversionUtil.createReadResourceSequence` is a public method that takes JSON-LD representing zero, one or more resources and returns an array of `ReadResource`. For each resource serialized as JSON-LD, `ResourcesConversionUtil.createReadResource` is called to do the conversion to a `ReadResource`. As a first step, `ResourcesConversionUtil.createReadResource` determines the resource's type (its class). Then, the definition for this class is requested from `OntologyCache`. The class definition contains information such as the class's label, cardinalities for properties and the definitions of those properties. The cardinalities are required to distinguish between system properties and properties that are defined in a project ontology. Each property value serialized as JSON-LD is converted to a `ReadValue` if there exists a cardinality for it for the resource class at hand.


"zero, one, or more" - the additional comma makes it easier to comprehend

the sentence at the end
"Each property value serialized as JSON-LD is converted to a ReadValue if a cardinality for it exists for the resource class at hand."

done in cc70b8e

mdelez · 2020-12-03T09:20:22Z

design-documentation.md


 ### Generic Cache

-`GenericCache` is an abstract and generic class. The generic type is the type of object that is going to be cached, e.g., an `ReadOntology`. The key is the IRI of the object that is cached. `GenericCache` ensures that a specific element is only requested once from Knora also if several asynchronous for the same element are performed. `GenericCache` also resolves dependencies of an element that is being requested, but in a non blocking ay, i.e. the requested element is returned immediately it is ready while the dependencies are still being resolved.
+`GenericCache` is an abstract and generic class. The generic type is the type of object that is going to be cached, e.g., an `ReadOntology`. The key is the IRI of the object that is cached. `GenericCache` ensures that a specific element is only requested once from DSP-API also if several asynchronous for the same element are performed. `GenericCache` also resolves dependencies of an element that is being requested, but in a non blocking ay, i.e. the requested element is returned immediately it is ready while the dependencies are still being resolved.


"GenericCache ensures that a specific element is only requested once from DSP-API if several asynchronous for the same element are performed." - remove "also"

"but in a non-blocking way, i.e. the requested element is returned immediately when it is ready while the dependencies are still being resolved."

done in cc70b8e

mdelez · 2020-12-03T09:22:19Z

test-framework/README.md


-Then, open the root directory of the library in the terminal and run
+Then switch to the directory `./test-framework`. 
+From this directory, run the follwoing scripts:


done in cc70b8e

tobiasschweizer · 2020-12-03T13:42:30Z

after discussion with @kilchenmann and @mpro7: I will add links to the Markdown files and add a section in the README saying that these links always point to the latest version of the file, not necessarily the version / release the user is currently using.

tobiasschweizer · 2020-12-03T14:53:47Z

GitHub docs suggest to use relative links: https://docs.github.com/en/free-pro-team@latest/github/creating-cloning-and-archiving-repositories/about-readmes#relative-links-and-image-paths-in-readme-files

however, I am not sure how this looks on npm

tobiasschweizer · 2020-12-03T14:59:48Z

I checked https://www.npmjs.com/package/rxjs and I figured that relative links are rewritten so they point to the location on GitHub.

tobiasschweizer · 2020-12-03T15:19:40Z

@mpro7 I added the @category tag to the metadata endpoint. Once the whole implementation of the metadata endpoint is done, we should categorise all classes correctly. I did not do it yet because this would create merge conflicts.

mdelez

Very nice :)

docs (README): rename existing README and start fresh

301c858

tobiasschweizer added the documentation Add or update doc files label Nov 25, 2020

tobiasschweizer self-assigned this Nov 25, 2020

Tobias Schweizer added 12 commits November 25, 2020 16:17

docs (README): add section "Getting Started"

29a5628

docs (README): add more explanations

33a189a

docs (README): remove blank lines

3940e24

docs (README): small adaptions

dbdfb4f

docs (typedoc): change options

62a448a

docs (typedoc): change options

d6610ae

docs (typedoc): change options

58dfde0

docs (typedoc): change options, flag constructs as internal

b3bac36

docs (typedoc): flag internally used constructs as @internal

6d5aaea

docs (typedoc): flag internally used constructs as @internal

03d545f

docs (typedoc): flag internally used constructs as @internal

ca82469

docs (typedoc): flag internally used constructs as @internal

42c78e9

tobiasschweizer mentioned this pull request Nov 30, 2020

DSP-1064 Create metadata endpoint in JS-LIB #258

Merged

Tobias Schweizer added 5 commits November 30, 2020 12:22

docs (typedoc): use the @category tag

b7731a7

docs (typedoc): use the @category tag

af6ba05

docs (typedoc): use the @category tag

6e43437

docs (typedoc): use the @category tag

c24625b

docs (typedoc): use the @category tag

351d771

tobiasschweizer changed the title ~~Improved Docs~~ Improve Docs Nov 30, 2020

Tobias Schweizer added 8 commits November 30, 2020 13:14

docs (typedoc): use the @category tag

06e3a3f

docs (typedoc): use JSON file for config

02c469b

docs (typedoc): use the @category tag

546eefb

docs (typedoc): use the @category tag

7555523

docs (README): small improvements

b4d3bfe

docs (dev docs): reorganize dev docs

bf5173d

docs (dev docs): explain dev version

455dfcf

docs (dev docs): explain test data integration

2b9088f

Tobias Schweizer added 2 commits December 2, 2020 11:14

docs (contribution.md): use DSP-API consistently

83a3c1f

docs (README): fix typo

d00560f

tobiasschweizer requested a review from mpro7 December 2, 2020 10:25

mpro7 requested changes Dec 2, 2020

View reviewed changes

Tobias Schweizer added 2 commits December 2, 2020 14:10

docs (README): mention desig-documentation.md

5c3918a

docs (README): clarify script description

f120a33

mpro7 self-requested a review December 2, 2020 13:32

mpro7 approved these changes Dec 2, 2020

View reviewed changes

Merge branch 'main' into wip/dsp-1050-docs

899c4fe

mdelez requested changes Dec 3, 2020

View reviewed changes

Tobias Schweizer added 3 commits December 3, 2020 14:55

docs (README): fixes

12cd1f1

docs (contribution): fixes

8a12b84

docs (design docs): fixes

cc70b8e

Tobias Schweizer added 2 commits December 3, 2020 16:10

docs (README): links

9e1e420

docs (README): links

ade326d

tobiasschweizer requested review from mdelez, kilchenmann and mpro7 December 3, 2020 15:13

docs (metadata endpoint): use @category tag

3701f22

mdelez approved these changes Dec 3, 2020

View reviewed changes

mpro7 approved these changes Dec 3, 2020

View reviewed changes

tobiasschweizer merged commit 95c57c3 into main Dec 3, 2020

tobiasschweizer deleted the wip/dsp-1050-docs branch December 3, 2020 16:26

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve Docs #264

Improve Docs #264

tobiasschweizer commented Nov 25, 2020 •

edited

tobiasschweizer commented Dec 2, 2020

mpro7 left a comment

mpro7 Dec 2, 2020

tobiasschweizer commented Dec 2, 2020

mpro7 left a comment •

edited

tobiasschweizer commented Dec 2, 2020

mdelez left a comment

mdelez Dec 2, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 2, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 2, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 2, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 2, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 3, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 3, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 3, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 3, 2020

tobiasschweizer Dec 3, 2020

mdelez Dec 3, 2020

tobiasschweizer Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

mdelez left a comment


		Below you may find a minimal example in TypeScript for the process of the user login.
		Make sure that `rxjs` is installed in the required major version 6 with the framework you are using, e.g. Angular.


		## Introduction

		The purpose of this library is facilitating the use of [DSP-API (Knora)](https://www.knora.org) in web client development.

Improve Docs #264

Improve Docs #264

Conversation

tobiasschweizer commented Nov 25, 2020 • edited

tobiasschweizer commented Dec 2, 2020

mpro7 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tobiasschweizer commented Dec 2, 2020

mpro7 left a comment • edited

Choose a reason for hiding this comment

tobiasschweizer commented Dec 2, 2020

mdelez left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

tobiasschweizer commented Dec 3, 2020

mdelez left a comment

Choose a reason for hiding this comment

tobiasschweizer commented Nov 25, 2020 •

edited

mpro7 left a comment •

edited