Skip to content

Commit

Permalink
docs: update README.md
Browse files Browse the repository at this point in the history 
Closes: #361
  • Loading branch information
@b1rger
b1rger committed Oct 18, 2023
1 parent 025186f commit b52d1d8
Showing 1 changed file with 70 additions and 172 deletions.
242 changes: 70 additions & 172 deletions README.rst
View file
Original file line number Diff line number Diff line change
@@ -1,218 +1,116 @@
Readme
======
APIS
====

The APIS_ project intents to semantically annotate the Austrian Bibliography Lexicon (ÖBL_). To achieve this goal
we develop(ed) this web-app. It is based on a 5 entities (person, place, institution, event, work) data model.
All 5 entities are connected to each other. Entities, as well as relations between them, can be typed with vocabularies
similar to the Simple Knowledge Organization System (SKOS_).
The `Austrian Prosophographic Information System` is a
[Django](https://www.djangoproject.com/) based prosopography framework. It
allows to create web applications to manage entities and relations between
entities. It provides API access to the data in various formats and creates
swagger defintions. A swagger-ui allows for comfortable access to the data.

While a default APIS installation uses the 5 entities data model described above, this data model can be rather easily adapted
to whatever fits best to the project using it. Frontend and RestAPI automatically adapt to changes in the data model.
Data can also be imported from remote resources described in
[RDF](https://en.wikipedia.org/wiki/Resource_Description_Framework).

In addition to this configurable import of data via RDF, there is also an configurable serialization of data. The generic RestAPI
of APIS provides data either in the internal JSON format, TEI or RDF (serialized with `CIDOC CRM`_).
In addition to this configurable import of data via RDF, there is also an
configurable serialization of data. The generic RestAPI of APIS provides data
either in the internal JSON format, TEI or RDF (serialized with `CIDOC CRM`_).

APIS comes with a built in system of autocompletes that allows researchers to import meta-data of entities with just a
single click. Out of the box APIS supports Stanbol_ as a backend for the autocompletes, but the system is rather easy to
adapt to any Restfull API. APIS also supports the parsing of RDFs_ describing entities into an entity. The parsing is
configured in a settings file.
APIS comes with a built in system of autocompletes that allows researchers to
import meta-data of entities with just a single click. Out of the box APIS
supports Stanbol_ as a backend for the autocompletes, but the system is rather
easy to adapt to any Restfull API. APIS also supports the parsing of RDFs_
describing entities into an entity. The parsing is configured in a settings
file.

APIS has a mnodular structure and its core functionalities (provided by this library) can be extended with further modules.
Currently there are:
* apis-highlighter_: apis-highlighter provides offset annotation features to apis-core. It can be used to annotate any
text stored in APIS and link the annotations to any object in APIS (entities, relations, vocabularies...). The forms
used to create relations, entities etc. can be reused in the highlighter and annotators can create entities and annotations
in one step. The annotations can also be organized in so-called annotation projects and provided to frontends via the API.
Forms and context menus can be configured in the admin backend.
* apis-bibsonomy_: apis-bibsonomy provides the possibility to add bibliographic references to either whole objects or single
attributes of these objects. As a backend for managing these bibliographic references one can use either zotero_ or bibsonomy_.

For a demo of the application please refer to apisdev_.


Installation
------------

The installation process is described in the apis-core docs_.
*Entities*

*Relations*

Licensing
---------

All code unless otherwise noted is licensed under the terms of the MIT License (MIT). Please refer to the file LICENSE in the root directory of this repository.

All documentation and images unless otherwise noted are licensed under the terms of Creative Commons Attribution-ShareAlike 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/
All code unless otherwise noted is licensed under the terms of the MIT License
(MIT). Please refer to the file LICENSE in the root directory of this
repository.

All documentation and images unless otherwise noted are licensed under the
terms of Creative Commons Attribution-ShareAlike 4.0 International License. To
view a copy of this license, visit
http://creativecommons.org/licenses/by-sa/4.0/

.. _APIS: https://www.oeaw.ac.at/acdh/projects/apis/
.. _apisdev: https://apis.acdh-dev.oeaw.ac.at
.. _ÖBL: http://www.biographien.ac.at
.. _SKOS: https://en.wikipedia.org/wiki/Simple_Knowledge_Organization_System
.. _Stanbol: https://stanbol.apache.org/
.. _RDFs: https://en.wikipedia.org/wiki/Resource_Description_Framework
.. _docs: https://acdh-oeaw.github.io/apis-core/
.. _apis-highlighter: https://github.com/acdh-oeaw/apis_highlighter
.. _apis-bibsonomy: https://github.com/acdh-oeaw/apis-bibsonomy
.. _`CIDOC CRM`: http://www.cidoc-crm.org/


Install the package
Installation
------------

things which needs to be added to the project's settings and urls files

# mandatory:

## add apis-apps to `INSTALLED_APPS`
Create a project using your favourite package manager:

```
...
'apis_core.apis_entities',
'apis_core.apis_metainfo',
'apis_core.apis_relations',
'apis_core.apis_vocabularies',
'apis_core.apis_labels',
...
poetry new foobar --name apis_ontology
```

## add apis specific context_processors

```
'OPTIONS': {
'context_processors': [
...
'webpage.webpage_content_processors.is_dev_version',
'apis_core.context_processors.custom_context_processors.add_entities',
...
],
},
```

## APIS_ENTITIES

todo!
Currently (as of 2023-10) the name of the apis application **has** to be
`apis_ontology` - this is considered a bug and is tracked in [this bug
report](https://github.com/acdh-oeaw/apis-core-rdf/issues/100).

configure the default columns for entitiy list views
In your project folder, add apis as a dependency:

```
'table_fields': [
'name', 'lat', 'lng'
],
```

configure which columns users can add to the default list view

```
'additional_cols': [
'lat', 'lng', 'part_of'
],
poetry add git+https://github.com/acdh-oeaw/apis-core-rdf#v0.6.1
```


## Filter configuration for Relation Views

Filters for list views for apis relations are generated by `apis_core.apis_relations.rel_filters.get_filters` and can be configured via specific settings parameters in the project's settings file. You can provide a list `APIS_RELATIONS_FILTER_EXCLUDE` with (sub)strings of field names which should be excluded from the filter.

The list below provides a reasonable default:

Setup your Django project
```
APIS_RELATIONS_FILTER_EXCLUDE = [
'uri',
'tempentityclass',
'user', '__id',
'source',
'label',
'temp_entity',
'collection__',
'_ptr',
'baseclass',
'id',
'written',
'relation_type__description',
'relation_type__parent_class',
'relation_type__status',
'relation_type__vocab_name',
'relation_type__name_reverse',
'__text',
]
rm -rf apis_ontology
poetry run django-admin startproject apis_ontology .
```


Additionally you can exclude fields on class level:

Now start using your Django project
```
APIS_RELATIONS = {
'PersonPlace': {
'exclude': ['name']
}
}
poetry run ./manage.py runserver
```

# optional:

## APIS_NEXT_PREV

In case you set this parameter to `False` then `apis_core.apis_metainfo.TempEntityClass.get_prev_url()` and `apis_core.apis_metainfo.TempEntityClass.get_next_url()` methods return `False`. Set this param to deactivate the prev/next browsing function in the entitie's detail view. Default (if not set) is `True`


## APIS_BASE_URI
To use the APIS framework in your application, add the following APIS modules to your Django settings module:

This parameter is used to construct URIs for Apis Entities in case no external URIs (like geonames or gnd) are provided, defaults to `http://apis.info`

e.g. `APIS_BASE_URI = 'https://myprocect/objects/'` will create a URI like `https://myprocect/objects/1234`

## log-in-restrictions
If theese settings are missing or set to `False` not logged in users will be redirected to log-in page

```
APIS_LIST_VIEWS_ALLOWED = True
APIS_DETAILKJL_VIEWS_ALLOWED = True
```
'apis_ontology',
'apis_core.core',
'apis_core.apis_entities',
'apis_core.apis_metainfo',
'apis_core.apis_relations',
'apis_core.apis_vocabularies',
'apis_core.apis_labels',

## Override the entities' list view template:

Change the template name in the project's settings file by adding the following variable

`APIS_LIST_VIEW_TEMPLATE = "generic_list.html"`
`APIS_DELETE_VIEW_TEMPLATE = "webpage/confirm_delete.html"`

## TEI

In case you store TEI encoded XML in you TEXT objects, you can display those with https://github.com/TEIC/CETEIcean. Therefore you'll need to list the values of `Text.kind.name` in a settings parameter.
Let's say that all TEI texts are stored in Text fields with kind "xml/tei transcription":
```

`APIS_TEI_TEXTS = ['xml/tei transcription']`
Additional Django applications neede for APIS:

You'll also need to set define the locations for the CETEICEAN specific static files via dedicated paramters:
* "apis_override_select2js"

```
APIS_CETEICEAN_CSS = "http://teic.github.io/CETEIcean/css/CETEIcean.css"
APIS_CETEICEAN_JS = "http://teic.github.io/CETEIcean/js/CETEI.js"
poetry add git+https://github.com/acdh-oeaw/apis-override-select2js#v0.1.0
```

This is a workaround for APIS' handling of autocomplete forms. You will need it
if you want to use autocomplete.

## IIIF

In case you want to dipslay images served via IIIF protocoll add the following params to your settings files

You will also need the following dependencies:
```
APIS_IIIF_WORK_KIND = 'IIIF'
APIS_IIIF_ENT_IIIF_REL = "has iiif image"
APIS_IIIF_SERVER = "https://iiif.acdh.oeaw.ac.at/"
# APIS_OPENSEADRAGON_CSS = "https://teic.github.io/CETEIcean/css/CETEIcean.css"
APIS_OSD_JS = "https://cdnjs.cloudflare.com/ajax/libs/openseadragon/2.4.0/openseadragon.min.js"
APIS_OSD_IMG_PREFIX = "https://cdnjs.cloudflare.com/ajax/libs/openseadragon/2.4.0/images/"
poetry add django-crispy-forms django-filter django-tables2 django-autocomplete-light django-rest-framework drf-spectacular
```
Add them to the `INSTALLED_APPS`:

custom management commands
------------

`python manage.py import_rel_vocabs {path-to-excel-file}`
```
# ui stuff
"crispy_forms",
"django_filters",
"django_tables2",
"dal",
"dal_select2",

Excel-File needs to match following conventions:
# api
"rest_framework",
"rest_framework.authtoken",

sheet name needs to be the class name of the Vocab class, e.g. PersonWorkRelation
# for swagger ui generation
"drf_spectacular",

sheets need column-header `ebene_1`, `ebene_2`, ...
field values: name|name_reverse; if no name_reverse value is provided, name_reverse is the same as name
all vocabs in one row are linked with as parent_classes, column one does not have a parent class, column 2 (`ebene_2`) takes as parent value from class ebene_1
```

0 comments on commit b52d1d8

Please sign in to comment.