Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve docs (DEV-450) #152

Merged
merged 7 commits into from Feb 17, 2022
Merged

docs: improve docs (DEV-450) #152

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
08b2b89
improve docs
jnussbaum Feb 9, 2022
f01c788
Merge branch 'main' into wip/dev-450-improve-docs
jnussbaum Feb 11, 2022
31a9f27
correct the heading hierarchy of CHANGELOG.md
jnussbaum Feb 15, 2022
88b9931
Instad of layout-hacking, adapt the CSS to have more top-padding for …
jnussbaum Feb 15, 2022
1384483
adapt layout
jnussbaum Feb 15, 2022
f491d31
update pyproject.toml for autopep8
jnussbaum Feb 16, 2022
0fa6489
Merge branch 'main' into wip/dev-450-improve-docs
jnussbaum Feb 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
32 changes: 16 additions & 16 deletions CHANGELOG.md
View file
Open in desktop
Expand Up @@ -13,7 +13,7 @@

* **xmlupload:** use custom IRIs created from salsah ARKs for XML upload (DEV-179) ([#147](https://www.github.com/dasch-swiss/dsp-tools/issues/147)) ([873324a](https://www.github.com/dasch-swiss/dsp-tools/commit/873324ad4cd4fefd48d8d2fc37f08774285849d5))

### [1.8.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.8.0...v1.8.1) (2022-01-11)
## [1.8.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.8.0...v1.8.1) (2022-01-11)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the CHANGELOG.md is automatically created. So changing stuff here will lead to inconsistencies in the future, once more automatic stuff is added... I'd suggest not doing this, but it's up to you.
(In case you're wondering why sometimes the versions are h2 and sometimes they are h3: that's the difference between minor and patch releases.)



### Bug Fixes
Expand Down Expand Up @@ -45,7 +45,7 @@

* improve ontology schema and extend tests (DEV-313) ([#140](https://www.github.com/dasch-swiss/dsp-tools/issues/140)) ([656ccff](https://www.github.com/dasch-swiss/dsp-tools/commit/656ccff0ff553b13b19242c9997220600e53a76f))

### [1.7.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.7.0...v1.7.1) (2021-12-14)
## [1.7.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.7.0...v1.7.1) (2021-12-14)


### Bug Fixes
Expand Down Expand Up @@ -76,7 +76,7 @@

* update DSP-Tools to support ArchiveRepresentation (DEV-259) ([#128](https://www.github.com/dasch-swiss/dsp-tools/issues/128)) ([85a40c2](https://www.github.com/dasch-swiss/dsp-tools/commit/85a40c203d0fa7afc7f7bb122aac0860c304acf4))

### [1.6.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.6.0...v1.6.1) (2021-11-25)
## [1.6.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.6.0...v1.6.1) (2021-11-25)


### Bug Fixes
Expand All @@ -103,14 +103,14 @@

* **id-to-iri:** extend xmlupload to allow references to existing resources (DEV-60) ([#108](https://www.github.com/dasch-swiss/dsp-tools/issues/108)) ([40b01db](https://www.github.com/dasch-swiss/dsp-tools/commit/40b01db9d32353dce048e60f48e1454ff7a9bbd5))

### [1.5.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.1...v1.5.2) (2021-11-16)
## [1.5.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.1...v1.5.2) (2021-11-16)


### Maintenance

* **documentation:** add missing documentation for excel2resources (DEV-144) ([cde0db5](https://www.github.com/dasch-swiss/dsp-tools/commit/cde0db5fc925055c0b7a5b3ff3706afd26497f8c))

### [1.5.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.0...v1.5.1) (2021-10-13)
## [1.5.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.5.0...v1.5.1) (2021-10-13)


### Bug Fixes
Expand All @@ -131,7 +131,7 @@

* **docs:** fix example in documentation (DSP-1740) ([#99](https://www.github.com/dasch-swiss/dsp-tools/issues/99)) ([11cdd72](https://www.github.com/dasch-swiss/dsp-tools/commit/11cdd72911e41d837a99579caf0d9d799b0360fc))

### [1.4.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.4.0...v1.4.1) (2021-09-20)
## [1.4.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.4.0...v1.4.1) (2021-09-20)


### Maintenance
Expand All @@ -151,21 +151,21 @@
* **excel-to-properties:** create properties from Excel (DSP-1577) ([#89](https://www.github.com/dasch-swiss/dsp-tools/issues/89)) ([9f48e9a](https://www.github.com/dasch-swiss/dsp-tools/commit/9f48e9ae580121e01896fc4f2f8491da8150a180))
* **excel-to-resources:** create resources from excel (DSP-1576) ([#88](https://www.github.com/dasch-swiss/dsp-tools/issues/88)) ([7b0302f](https://www.github.com/dasch-swiss/dsp-tools/commit/7b0302f2feed3475f908c3915ce89d9b5d423d11))

### [1.3.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.2...v1.3.3) (2021-09-07)
## [1.3.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.2...v1.3.3) (2021-09-07)

### Bug Fixes

* wrong values &
property ([#86](https://www.github.com/dasch-swiss/dsp-tools/issues/86)) ([7cf6405](https://www.github.com/dasch-swiss/dsp-tools/commit/7cf6405ad045bbd97d34bc2d0a2d4872e873a78e))

### [1.3.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.1...v1.3.2) (2021-08-17)
## [1.3.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.1...v1.3.2) (2021-08-17)

### Bug Fixes

* **import:** fix import error when starting script directly (
DSP-1869) ([05b1eb1](https://www.github.com/dasch-swiss/dsp-tools/commit/05b1eb148b3dbb2c3c4c38f85cfaa7aa782c2641))

### [1.3.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.0...v1.3.1) (2021-08-11)
## [1.3.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.3.0...v1.3.1) (2021-08-11)

### Bug Fixes

Expand All @@ -179,7 +179,7 @@
* **excel-lists:** create multilanguage json lists from excel files (
DSP-1580) ([#75](https://www.github.com/dasch-swiss/dsp-tools/issues/75)) ([06d071a](https://www.github.com/dasch-swiss/dsp-tools/commit/06d071a6d47cd1002610c70b076319236bdab0db))

### [1.2.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.2.0...v1.2.1) (2021-07-27)
## [1.2.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.2.0...v1.2.1) (2021-07-27)

### Bug Fixes

Expand All @@ -193,14 +193,14 @@
* **verbose xml upload:** use v option to print verbose output in XML upload (
DSP-1797) ([#70](https://www.github.com/dasch-swiss/dsp-tools/issues/70)) ([b1f56a1](https://www.github.com/dasch-swiss/dsp-tools/commit/b1f56a1efe8ff32376c8e4f8bf8f292d6061e016))

### [1.1.6](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.5...v1.1.6) (2021-07-22)
## [1.1.6](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.5...v1.1.6) (2021-07-22)

### Documentation

* add
changelog ([#71](https://www.github.com/dasch-swiss/dsp-tools/issues/71)) ([ce1feab](https://www.github.com/dasch-swiss/dsp-tools/commit/ce1feab45e15cb203447a906c93b7caaf951670e))

### [1.1.5](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.4...v1.1.5) (2021-07-14)
## [1.1.5](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.4...v1.1.5) (2021-07-14)

### Documentation

Expand All @@ -209,21 +209,21 @@
* **dsp-tools-xmlupload:** addition to incomplete paragraph (
DSP-1693) ([#67](https://www.github.com/dasch-swiss/dsp-tools/issues/67)) ([318547f](https://www.github.com/dasch-swiss/dsp-tools/commit/318547fd58fd015209b42a1279baef11056b585d))

### [1.1.4](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.3...v1.1.4) (2021-06-16)
## [1.1.4](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.3...v1.1.4) (2021-06-16)

### Documentation

* add copyright information to docs (
DSP-1190) ([#65](https://www.github.com/dasch-swiss/dsp-tools/issues/65)) ([0174c4a](https://www.github.com/dasch-swiss/dsp-tools/commit/0174c4afda601047a92669a2f1f92a05d75999cb))

### [1.1.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.2...v1.1.3) (2021-06-08)
## [1.1.3](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.2...v1.1.3) (2021-06-08)

### Documentation

* update readme after documentation update (
DSP-1693) ([#63](https://www.github.com/dasch-swiss/dsp-tools/issues/63)) ([7b7dcca](https://www.github.com/dasch-swiss/dsp-tools/commit/7b7dcca55c729aa6bf995c04ae37f50a630bf9a5))

### [1.1.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.1...v1.1.2) (2021-06-07)
## [1.1.2](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.1...v1.1.2) (2021-06-07)

### Maintenance

Expand All @@ -235,7 +235,7 @@
* improve documentation (
DSP-1693) ([#62](https://www.github.com/dasch-swiss/dsp-tools/issues/62)) ([591b5ad](https://www.github.com/dasch-swiss/dsp-tools/commit/591b5ad46f8c4b6aecd023ff1448953a7c6c7d45))

### [1.1.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.0...v1.1.1) (2021-04-20)
## [1.1.1](https://www.github.com/dasch-swiss/dsp-tools/compare/v1.1.0...v1.1.1) (2021-04-20)

### Bug Fixes

Expand Down
16 changes: 16 additions & 0 deletions docs/assets/style/theme.css
View file
Open in desktop
Expand Up @@ -2,3 +2,19 @@
.md-tabs {
background-color: rgb(89, 73, 167) !important;
}
h1 {
font-weight: bold;
padding-top: 50px;
}
h2 {
font-weight: bold;
padding-top: 50px;
}
h3 {
font-weight: bold;
padding-top: 50px;
}
h4 {
font-weight: bold;
padding-top: 50px;
}
Comment on lines +5 to +20
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Notice that this might only affect the docs at https://dasch-swiss.github.io/dsp-tools/ . If you want it to take effect on docs.dasch.swiss, you may have to change things on the docs repo too. (I'm not sure though.)

42 changes: 21 additions & 21 deletions docs/dsp-tools-create-ontologies.md
View file
Open in desktop
Expand Up @@ -85,7 +85,7 @@ The following fields are mandatory:

The following fields are optional:

- `comments` (but if omitted a default value `[no comment provided]`) is used
- `comments`
- `super` (with the exception of `LinkValue` where `super` is mandatory)
- `subject`
- `gui_attributes`
Expand All @@ -112,7 +112,7 @@ A resource object needs to have the following fields:

The following field is optional:

- `comments` (but if omitted a default value `[no comment provided]`) is used
- `comments`

A detailed description of `resources` can be found [below](#properties-object-in-detail).

Expand Down Expand Up @@ -150,8 +150,7 @@ and "it" are supported).

`"comments": { "<lang>": "<comment>", "<lang>": "<comment>", ... }`

Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is mandatory but
can be omitted. In that case the default value `[no comment provided]` (with language "en") is used.
Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is optional.

### Super

Expand All @@ -170,9 +169,9 @@ The following base properties are defined by DSP:
- `hasLinkTo`: This value represents a link to another resource. You have to indicate the "_object_" as a prefixed name
that identifies the resource class this link points to (a ":" prepended to the name is sufficient if the resource is
defined in the current ontology).
- `hasColor`: Defines a color value (_ColorValue_)
- `hasComment`: Defines a "standard" comment
- `hasGeometry`: Defines a geometry value (a JSON describing a polygon, circle or rectangle), see _ColorValue_
- `hasColor`: Defines a color value
- `hasComment`: Defines a standard comment
- `hasGeometry`: Defines a geometry value (a JSON describing a polygon, circle or rectangle)
- `isPartOf`: A special variant of _hasLinkTo_. It says that an instance of the given resource class is an integral part
of another resource class. E.g. a "page" is part of a "book".
- `isRegionOf`: A special variant of _hasLinkTo_. It means that the given resource class is a "region" of another
Expand All @@ -196,7 +195,7 @@ Example of a `properties` object:
],
"labels": {
"en": "School ID",
"de": "ID der Schule"
"de": "ID der Schule",
"fr": "ID de l'école"
},
"gui_element": "SimpleText",
Expand Down Expand Up @@ -320,7 +319,7 @@ A string representation of the color in the hexadecimal form e.g. "#ff8000".
{
"name": "hasColor",
"super": [
"hasValue"
"hasColor"
],
"object": "ColorValue",
"labels": {
Expand Down Expand Up @@ -458,7 +457,7 @@ or moving images.
{
"name": "hasGeometry",
"super": [
"hasValue"
"hasGeometry"
],
"object": "GeomValue",
"labels": "Geometry",
Expand Down Expand Up @@ -606,7 +605,7 @@ Represents a time-interval
- _gui_attributes_:
- `maxlength=integer` (optional): The maximum number of characters accepted
- `size=integer` (optional): The size of the input field
- `Interval`: not yet implemented.
- `Interval`: Two spin boxes, one for each decimal
- _gui_attributes_: No attributes

*Example:*
Expand Down Expand Up @@ -759,26 +758,28 @@ and "it" are supported).

`"super": ["<super-resource>", "<super-resource>", ...]`

A resource is always derived from at least one other resource. The most generic resource class for DSP is `Resource`. A resource may be derived from resources defined in external ontologies.
A resource is always derived from at least one other resource. The most generic resource class for DSP is `Resource`.
A resource may be derived from resources defined in external ontologies.

The following predefined resources are provided by DSP:

- `Resource`: A generic resource that represents an item from the real world
- `StillImageRepresentation`: An object that is connected to a still image
- `TextRepresentation`: An object that is connected to an (external) text (not yet implemented)
- `AudioRepresentation`: An object representing audio data (not yet implemented)
- `Resource`: A generic resource representing an item from the real world. This is the most general case, to be
used in all cases when your resource is none of the special cases below.
- `StillImageRepresentation`: An object representing a still image
- `TextRepresentation`: An object representing an (external) text (not yet implemented)
- `AudioRepresentation`: An object representing an audio file
- `DDDRepresentation`: An object representing a 3-D representation (not yet implemented)
- `DocumentRepresentation`: An object representing an opaque document (e.g. a PDF)
- `MovingImageRepresentation`: An object representing a moving image (video, film)
- `ArchiveRepresentation`: An object representing a archive file (e.g. Zip)
- `ArchiveRepresentation`: An object representing an archive file (e.g. Zip)
- `Annotation`: A predefined annotation object. It has automatically the following predefined properties defined:
- `hasComment` (1-n)
- `isAnnotationOf` (1)
- `LinkObj`: A resource class linking together several other, generic, resource classes. The class has the following
- `LinkObj`: A resource class linking together several other resource classes. The class has the following
properties:
- `hasComment` (1-n)
- `hasLinkTo` (1-n)
- `Region`: Represents a simple region. The class has the following properties:
- `Region`: Represents a region in an image. The class has the following properties:
- `hasColor` (1)
- `isRegionOf` (1)
- `hasGeometry` (1)
Expand Down Expand Up @@ -812,8 +813,7 @@ resource can have as well as how many times the relation is established.

`"comments": { "<lang>": "<comment>", "<lang>": "<comment>", ... }`

Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is mandatory but
can be omitted. In that case the default value `[no comment provided]` (with language "en") is used.
Comments with language tags. Currently, "de", "en", "fr" and "it" are supported. The `comments` element is optional.

Example for a resource definition:

Expand Down
3 changes: 1 addition & 2 deletions docs/dsp-tools-information-for-developers.md
View file
Open in desktop
Expand Up @@ -46,7 +46,6 @@ in `pyproject.toml` in the root directory of the project.
```toml
[tool.autopep8]
max_line_length = 180
in-place = true
experimental = true

[tool.mypy]
Expand All @@ -56,7 +55,7 @@ show_column_numbers = true
strict = true
```

You can use the configuration with `autopep8 --global-config pyproject.toml [file path]`
You can use the configuration with `autopep8 --global-config pyproject.toml --in-place $FilePath$`
and `mypy --config-file pyproject.toml
[file path]`.

Expand Down