diff --git a/README.md b/README.md new file mode 100644 index 000000000..8ca1e0690 --- /dev/null +++ b/README.md @@ -0,0 +1,121 @@ +APIS +==== + +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. + +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`_). + +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. + +*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/ + + +Installation +------------ + +Create a project using your favourite package manager: + +```shell +poetry new foobar --name apis_ontology +``` + +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). + +In your project folder, add apis as a dependency: + +```shell +poetry add git+https://github.com/acdh-oeaw/apis-core-rdf#v0.6.1 +``` + +Setup your Django project +```shell +rm -rf apis_ontology +poetry run django-admin startproject apis_ontology . +``` + +Now start using your Django project +```shell +poetry run ./manage.py runserver +``` + +To use the APIS framework in your application, add the following APIS modules to your Django settings module: + +```python +"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", + +``` + +### Dependencies + +```shell +poetry add git+https://github.com/acdh-oeaw/apis-override-select2js#v0.1.0 +``` + +`apis_override_select2js` is a workaround for APIS' handling of autocomplete forms. You will need it +if you want to use autocomplete. Add it to your `INSTALLED_APPS` + +```python +"apis_override_select2js" +``` + + +You will also need the following dependencies: +```shell +poetry add django-crispy-forms django-filter django-tables2 django-autocomplete-light django-rest-framework drf-spectacular +``` +Add them to the `INSTALLED_APPS`: + +```python +# ui stuff +"crispy_forms", +"django_filters", +"django_tables2", +"dal", +"dal_select2", + +# api +"rest_framework", +"rest_framework.authtoken", + +# for swagger ui generation +"drf_spectacular", + +``` + +Now you should be ready to roll. Start creating your entities in you `apis_ontology/models.py`. diff --git a/README.rst b/README.rst deleted file mode 100644 index 24e1729d6..000000000 --- a/README.rst +++ /dev/null @@ -1,218 +0,0 @@ -Readme -====== - -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_). - -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. - -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 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_. - - -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/ - - -.. _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 ------------- - -things which needs to be added to the project's settings and urls files - -# mandatory: - -## add apis-apps to `INSTALLED_APPS` - -``` -... -'apis_core.apis_entities', -'apis_core.apis_metainfo', -'apis_core.apis_relations', -'apis_core.apis_vocabularies', -'apis_core.apis_labels', -... -``` - -## 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! - -configure the default columns for entitiy list views - - ``` - 'table_fields': [ - 'name', 'lat', 'lng' - ], -``` - -configure which columns users can add to the default list view - -``` - 'additional_cols': [ - 'lat', 'lng', 'part_of' - ], -``` - - -## 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: - -``` -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', -] -``` - - -Additionally you can exclude fields on class level: - -``` -APIS_RELATIONS = { - 'PersonPlace': { - 'exclude': ['name'] - } -} -``` - -# 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 - -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 -``` - -## 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']` - -You'll also need to set define the locations for the CETEICEAN specific static files via dedicated paramters: - -``` -APIS_CETEICEAN_CSS = "http://teic.github.io/CETEIcean/css/CETEIcean.css" -APIS_CETEICEAN_JS = "http://teic.github.io/CETEIcean/js/CETEI.js" -``` - - -## IIIF - -In case you want to dipslay images served via IIIF protocoll add the following params to your settings files - -``` -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/" -``` - -custom management commands ------------- - -`python manage.py import_rel_vocabs {path-to-excel-file}` - -Excel-File needs to match following conventions: - -sheet name needs to be the class name of the Vocab class, e.g. PersonWorkRelation - -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