docs: improve docs (DEV-450) (#152)

* improve docs * correct the heading hierarchy of CHANGELOG.md * Instad of layout-hacking, adapt the CSS to have more top-padding for headers * adapt layout * update pyproject.toml for autopep8
dasch-swiss · Feb 17, 2022 · be5b69f · be5b69f
1 parent 08ddebd
commit be5b69f
Show file tree

Hide file tree

Showing 5 changed files with 178 additions and 152 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -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)
 
 
 ### Bug Fixes
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 
@@ -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
 

diff --git a/docs/assets/style/theme.css b/docs/assets/style/theme.css
@@ -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;
+}
diff --git a/docs/dsp-tools-create-ontologies.md b/docs/dsp-tools-create-ontologies.md
@@ -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`
@@ -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).
 
@@ -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
 
@@ -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
@@ -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",
@@ -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": {
@@ -458,7 +457,7 @@ or moving images.
 {
   "name": "hasGeometry",
   "super": [
-    "hasValue"
+    "hasGeometry"
   ],
   "object": "GeomValue",
   "labels": "Geometry",
@@ -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:*
@@ -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)
@@ -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:
 

diff --git a/docs/dsp-tools-information-for-developers.md b/docs/dsp-tools-information-for-developers.md
@@ -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]
@@ -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]`.