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.
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
docs: improve docs (DEV-1478) #249
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -20,7 +20,7 @@ This documentation is divided into two parts: | |
|
||
A complete project definition looks like this: | ||
|
||
```json | ||
``` | ||
{ | ||
"prefixes": { | ||
"foaf": "http://xmlns.com/foaf/0.1/", | ||
|
@@ -32,10 +32,12 @@ A complete project definition looks like this: | |
"shortname": "BiZ", | ||
"longname": "Bildung in Zahlen", | ||
"descriptions": { | ||
... | ||
"en": "This is a simple example project", | ||
"de": "Dies ist ein einfaches Beispielprojekt" | ||
}, | ||
"keywords": [ | ||
... | ||
"example", | ||
"simple" | ||
], | ||
"lists": [ | ||
... | ||
|
@@ -113,38 +115,6 @@ The following fields are optional (if one or more of these fields are not used, | |
- groups | ||
- users | ||
|
||
A simple example definition of the `project` object looks like this: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. A complete example of a project is already given some lines above, so it doesn't make sense to repeat this here. |
||
|
||
```json | ||
{ | ||
"project": { | ||
"shortcode": "0809", | ||
"shortname": "test", | ||
"longname": "Test Example", | ||
"descriptions": { | ||
"en": "This is a simple example project", | ||
"de": "Dies ist ein einfaches Beispielprojekt" | ||
}, | ||
"keywords": [ | ||
"example", | ||
"simple" | ||
], | ||
"lists": [ | ||
... | ||
], | ||
"groups": [ | ||
... | ||
], | ||
"users": [ | ||
... | ||
], | ||
"ontologies": [ | ||
... | ||
] | ||
} | ||
} | ||
``` | ||
|
||
|
||
|
||
## "project" object in detail | ||
|
@@ -426,7 +396,7 @@ example, the list "colors" could be imported as follows: | |
"en": "A list with categories" | ||
}, | ||
"nodes": [ | ||
... | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This and other similar changes are just that PyCharm doesn't show that many problems. In the future, I'd like to look more frequently on the problems that are detected by PyCharm. But for this, I need to kick out the false positives. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Understandable (but confirms my dislike for PyCharm ;-)... in any case, I'm sure you could deactivate specific warnings). |
||
"..." | ||
] | ||
} | ||
] | ||
|
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -50,15 +50,18 @@ These steps are now explained in-depth: | |
|
||
|
||
## 1. Read in your data source | ||
|
||
In the first paragraph of the sample script, insert your ontology name, project shortcode, and the path to your data | ||
source. If necessary, activate one of the lines that are commented out. | ||
|
||
|
||
## 2. Create root element `<knora>` | ||
|
||
Then, the root element is created, which represents the `<knora>` tag of the XML document. | ||
|
||
|
||
## 3. Append the permissions | ||
|
||
As first children of `<knora>`, some standard permissions are added. At the end, please carefully check the permissions | ||
of the finished XML file to ensure that they meet your requirements, and adapt them if necessary. | ||
|
||
|
@@ -71,6 +74,7 @@ here](./dsp-tools-xmlupload.md#how-to-use-the-permissions-attribute-in-resources | |
|
||
|
||
## 4. Create list mappings | ||
|
||
Let's assume that your data source has a column containing list values named after the "label" of the JSON project list, | ||
instead of the "name" which is needed for the `dsp-tools xmlupload`. You need a way to get the names from the labels. | ||
If your data source uses the labels correctly, this is an easy task: The method `create_json_list_mapping()` creates a | ||
|
@@ -139,10 +143,12 @@ used. | |
|
||
|
||
## 5. Iterate through the rows of your data source | ||
|
||
With the help of Pandas, you can then iterate through the rows of your Excel/CSV, and create resources and properties. | ||
|
||
|
||
### 6. Create the `<resource>` tag | ||
|
||
There are four kind of resources that can be created: | ||
|
||
| super | tag | method | | ||
|
@@ -156,6 +162,7 @@ There are four kind of resources that can be created: | |
here](./dsp-tools-xmlupload.md#dsp-base-resources--base-properties-to-be-used-directly-in-the-xml-file). | ||
|
||
#### Resource ID | ||
|
||
Special care is needed when the ID of a resource is created. Every resource must have an ID that is unique in the file, | ||
and it must meet the constraints of xsd:ID. You can simply achieve this if you use the method `make_xsd_id_compatible()`. | ||
|
||
|
@@ -164,6 +171,7 @@ ID in a dict, so that you can retrieve it later. The example script contains an | |
|
||
|
||
### 7. Append the properties | ||
|
||
For every property, there is a helper function that explains itself when you hover over it. So you don't need to worry | ||
any more how to construct a certain XML value for a certain property. | ||
|
||
|
@@ -182,6 +190,7 @@ Here's how the Docstrings assist you: | |
|
||
|
||
#### Fine-tuning with `PropertyElement` | ||
|
||
There are two possibilities how to create a property: The value can be passed as it is, or as `PropertyElement`. If it | ||
is passed as it is, the `permissions` are assumed to be `prop-default`, texts are assumed to be encoded as `utf8`, and | ||
the value won't have a comment: | ||
|
@@ -214,6 +223,7 @@ make_text_prop( | |
|
||
|
||
#### Supported boolean formats | ||
|
||
For `make_boolean_prop(cell)`, the following formats are supported: | ||
|
||
- true: True, "true", "True", "1", 1, "yes", "Yes" | ||
|
@@ -222,7 +232,7 @@ For `make_boolean_prop(cell)`, the following formats are supported: | |
N/A-like values will raise an Error. So if your cell is empty, this method will not count it as false, but will raise an | ||
Error. If you want N/A-like values to be counted as false, you may use a construct like this: | ||
|
||
```python | ||
``` | ||
Comment on lines
-225
to
+235
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. again, this removes syntax highlighting I think, which reduces readability |
||
if excel2xml.check_notna(cell): | ||
# the cell contains usable content | ||
excel2xml.make_boolean_prop(":hasBoolean", cell) | ||
|
@@ -232,6 +242,7 @@ else: | |
``` | ||
|
||
#### Supported text values | ||
|
||
DSP's only restriction on text-properties is that the string must be longer than 0. It is, for example, possible to | ||
upload the following property: | ||
```xml | ||
|
@@ -243,22 +254,26 @@ upload the following property: | |
|
||
`excel2xml` allows to create such a property, but text values that don't meet the requirements of | ||
[`excel2xml.check_notna()`](#check-if-a-cell-contains-a-usable-value) will trigger a warning, for example: | ||
```python | ||
``` | ||
excel2xml.make_text_prop(":hasText", " ") # OK, but triggers a warning | ||
excel2xml.make_text_prop(":hasText", "-") # OK, but triggers a warning | ||
``` | ||
|
||
|
||
### 8. Append the resource to root | ||
|
||
At the end of the for-loop, it is important not to forget to append the finished resource to the root. | ||
|
||
|
||
## 9. Save the file | ||
|
||
At the very end, save the file under a name that you can choose yourself. | ||
|
||
|
||
## Other helper methods | ||
|
||
### Check if a cell contains a usable value | ||
|
||
The method `check_notna(cell)` checks a value if it is usable in the context of data archiving. A value is considered | ||
usable if it is | ||
|
||
|
@@ -308,6 +323,7 @@ In contrast, `check_notna(cell)` will return the expected value for all cases in | |
|
||
|
||
### Calendar date parsing | ||
|
||
The method `find_date_in_string(string)` tries to find a calendar date in a string. If successful, it | ||
returns the DSP-formatted date string. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think with that you remove syntax highlighting, which is good to have in my opinion