From 5b107cc08732ca78c6ea2f55e126f3c2b23f2706 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20Schl=C3=B6gl?= Date: Mon, 12 Aug 2024 11:10:25 +0200 Subject: [PATCH] docs: remove not used and outdated doc sections --- docs/source/autocomplete.rst | 35 -------- docs/source/data_model.rst | 72 ---------------- docs/source/development.rst | 43 ---------- docs/source/importing.rst | 29 ------- docs/source/index.rst | 6 -- docs/source/settings.rst | 129 ----------------------------- docs/source/user_documentation.rst | 45 ---------- 7 files changed, 359 deletions(-) delete mode 100644 docs/source/autocomplete.rst delete mode 100644 docs/source/data_model.rst delete mode 100644 docs/source/development.rst delete mode 100644 docs/source/importing.rst delete mode 100644 docs/source/settings.rst delete mode 100644 docs/source/user_documentation.rst diff --git a/docs/source/autocomplete.rst b/docs/source/autocomplete.rst deleted file mode 100644 index 054bfd5ed..000000000 --- a/docs/source/autocomplete.rst +++ /dev/null @@ -1,35 +0,0 @@ -Extending autocomplete results -============================== - -The autocomplete endpoint :py:class:`apis_core.generic.views.Autocomplete` can -be extended to provide additional autocomplete results, that are not -based on the default Django querysets. The autocomplete view always refers to a -Django model. To extend the results for a specific model, you have to create an -`ExternalAutocomplete` class, that is named after the model and resides in the -`querysets` module in the same app. So if you have an app called `myapp` with a -`models.py` - -.. code-block:: python - - class Person(models.Model): - name = models.CharField(max_length=255) - -then the respective autocomplete class should reside in `myapp.querysets` and -has to be called `PersonExternalAutocomplete`. - -.. code-block:: python - - class PersonExternalAutocomplete: - def extract_results(data): - ... do something with the data - return data - - def get_results(self, q): - with urllib.request.urlopen(f"https://some.uri.tld/search?q={q}") as f: - data = extract_results(json.loads(f.read())) - return results - return {} - -The class has to have a `get_results` method that receives a query as the first -parameter and returns a result in the format, the `django-autocomplete-light` -module uses- this is a dict with the keys "id", "text" and "selected_text". diff --git a/docs/source/data_model.rst b/docs/source/data_model.rst deleted file mode 100644 index e3bfb7d54..000000000 --- a/docs/source/data_model.rst +++ /dev/null @@ -1,72 +0,0 @@ -Data Model -========== - -Our internal data model consists of entities, relations, vocabularies and some meta-classes (e.g. annotations, -revisions etc.) - -.. _fig-data-model: - -.. figure:: /img/data_model_apis.png - :alt: Data model APIS - - Simplified data-model of the APIS webapp - -Please note that in the data-model schema in order to make the figure not too complex some arrows have been removed. - -Entities --------- - -The entities build the core of the internal APIS data-model: - -* :class:`entities.models.Person`: Natural persons -* :class:`entities.models.Place`: Any place on earth that can be defined by longitude and latitude. Mainly cities and countries. -* :class:`entities.models.Institution`: Any legal entity or legal entity similar entity. This includes obviously organisations, but also - religions, or long lasting prizes. -* :class:`entities.models.Event`: Any event that took place in history and is too big to model as a relation. This does not include a birth - of a person (like it would be modeled in event based data models) as the birth is split up between attributes (e.g. - the date of birth) and relations to other entities (e.g. the mother). It includes though wars and battles as these - would need a lot of entities to relate to each other. -* :class:`entities.models.Work`: Basically anything that human beings produce: letters and books, paintings, buildings and cars. - - -Relations ---------- - -Every entity in the APIS data model can be related to any other entity. Relations consist of: - -* a start entity (e.g. a person for a PersonPlace relation) -* a target entity (e.g. a place for a PersonPlace relation) -* start and end dates of the relation -* a vocabulary entry to define the kind of relation -* reference- and notes fields. These are full-text fields to further define the relation. - -There are - - -Vocabularies ------------- - -As we already mentioned we use SKOS_ like vocabularies to define entities and relations. These vocabulary entries -use following attributes: - -* *name*: the name of the entry. We define relations always in the direction the class is named. Thus the *PersonPlace* - relation needs a vocabulary entry describing the relation from the *Person* to the *Place*. E.g. "was educated in". -* *name_reverse*: Specifies the name to use for the reverse relation (*PlacePerson*). E.g. "was place of education of". -* *parent_class*: The parent of the entry. SKOS_ allows for hierarchical structures and we implement these hierarchies - by setting the parent class. -* *description*: Can be used to further define the entry. - - -Annotations ------------ - -The third important part of the data model are annotations. We store annotations as character offset with start and end -character (please see :class:`highlighter.models.Annotation` for details). Every :class:`highlighter.models.Annotation` -is associated with: - -* :class:`django.contrib.auth.models.User`: The user that created the annotation. Please keep in mind that this is not - changed when someone changes the associated relation or entity. -* an entity or relation (optional): anything within :ref:`entities-models` or :ref:`relations-models`. - - -.. _SKOS: https://en.wikipedia.org/wiki/Simple_Knowledge_Organization_System \ No newline at end of file diff --git a/docs/source/development.rst b/docs/source/development.rst deleted file mode 100644 index 0315aeb69..000000000 --- a/docs/source/development.rst +++ /dev/null @@ -1,43 +0,0 @@ -Development -=========== - -Dependencies ------------- - -* Django -* djangorestframework -* django-filter -* django-autocomplete-light -* django-cors-headers -* django-crum -* django-crispy-forms -* django-gm2m -* django-leaflet -* django-reversion -* django-tables2 -* djangorestframework-csv -* djangorestframework-xml -* rdflib -* drf-spectacular -* requests -* SPARQLWrapper -* django-model-utils -* django-admin-csvexport - - Used in the ``apis_labels`` and ``apis_vocabularies`` admin apps - -* tablib - - `You must have tablib installed in order to use the django-tables2 export functionality` - - the export functionality is used in the entities list view. - -* apis-override-select2js - - APIS overrides select2js to be able to provide autocomplete fields that also - integrate external sources. This package provides the patched Javascript - files - it has to be listed in ``INSTALLED_APPS`` *before* - ``django-autocomplete-light`` packages. - -* python-dateutil - - Used in ``apis_entities.autocomplete3`` diff --git a/docs/source/importing.rst b/docs/source/importing.rst deleted file mode 100644 index 3dd34053f..000000000 --- a/docs/source/importing.rst +++ /dev/null @@ -1,29 +0,0 @@ -Importing data from external resources -====================================== - -APIS provides the structure for easily importing data from external resources. -One main component for this are `Importer` classes. They always belong to a -Django Model, reside in the same app as the Djang model in the `importers` -module and are named after the Django Model. So if you have an app called -`myapp` with a `models.py` - -.. code-block:: python - - class Person(models.Model): - name = models.CharField(max_length=255) - -then the respective importer should reside in `myapp.importers` and has to be -called `PersonImporter`. - -An importer takes two arguments to instantiate: an `uri` and a `model`. The -importers task is then to create a model instance from this URI, usually by -fetching data from the URI, parsing it and extracting the needed fields. -The instance should then be returned by the `create_instance` method of the -importer. There is :py:class:`apis_core.generic.importers.GenericImporter` -which you can inherit from. - -To use this logic in forms, there is -:py:class:`apis_core.generic.forms.fields.ModelImportChoiceField` which is -based on `django.forms.ModelChoiceField`. It checks if the passed value starts -with `http` and if so, it uses the importer that fits the model and uses it to -create the model instance. diff --git a/docs/source/index.rst b/docs/source/index.rst index 2b2e0ed16..5714fc062 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,16 +15,10 @@ Welcome to APIS's documentation! installation configuration - settings customization - user_documentation history - data_model glossary - development collections - autocomplete - importing .. toctree:: :maxdepth: 2 diff --git a/docs/source/settings.rst b/docs/source/settings.rst deleted file mode 100644 index 92a0407a2..000000000 --- a/docs/source/settings.rst +++ /dev/null @@ -1,129 +0,0 @@ -Settings -======== - -This section deals with the internal configuration of the APIS tool. For instructions on how to set it up please refer -to :doc:`installation`. - - -REST_FRAMEWORK --------------- - -APIS uses the `Django Restframework`_ for API provisioning. Restframework specific settings like the default page size can be set here. - -.. code-block:: python - - REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"] = ( - "rest_framework.permissions.DjangoObjectPermissions", - ) - -Use the above default to allow setting permissions on object level. Meaning that every user gets his permissions depending on his/her user group and the collections this group has permissions for. -Set ``"rest_framework.permissions.DjangoModelPermissions"`` for allowing every user with permissions on a model to change all model instances. -Set ``"rest_framework.permissions.IsAuthenticated"`` if every logged in user should have all permissions. - -.. code-block:: python - - REST_FRAMEWORK["PAGE_SIZE"] = 50 - -Sets the default page size the APIS RestAPI should deliver. - - -SPECTACULAR_SETTINGS --------------------- - -We provide a custom schema generator for spectacular. -It is meant as a drop in replacement for the -"DEFAULT_GENERATOR_CLASS" of drf-spectacular. You can use it like this: - -.. code-block:: python - - SPECTACULAR_SETTINGS["DEFAULT_GENERATOR_CLASS"] = 'apis_core.generic.generators.CustomSchemaGenerator' - - -Background: - -The first reason is, that we are using a custom converter -(:class:`apis_core.generic.urls.ContenttypeConverter`) to provide access to views -and api views of different contenttypes. The default endpoint generator of the -drf-spectacular does not know about this converter and therefore sees the -endpoints using this converter as *one* endpoint with one parameter called -``contenttype``. Thats not what we want, so we have to do our own enumeration - -we iterate through all contenttypes that inherit from ``GenericModel`` and -create schema endpoints for those programatically. - -The second reason is, that the autoapi schema generator of DRF Spectacular -and our :class:`apis_core.generic.api_views.ModelViewSet` don't work well together. -Our ModelViewSet needs the dispatch method to set the model of the -``ModelViewSet``, but this method is not being called by the generator while -doing the inspection, which means the ``ModelViewSet`` does not know about the -model it should work with and can not provide the correct serializer and filter -classes. Therefore we create the callback for the endpoints by hand and set -the model from there. - - -APIS_BASE_URI -------------- - -.. code-block:: python - - APIS_BASE_URI = "https://your-url-goes-here.com" - -Sets the base URI your instance should use. This is important as APIS uses mainly URIs instead of IDs. These URIs are also used for the serialization. - - -APIS_NEXT_PREV --------------- - -.. code-block:: python - - APIS_NEXT_PREV = True - - -APIS_API_ID_WRITABLE ---------------------- - -.. code-block:: python - - APIS_API_ID_WRITABLE = False - - -Boolean setting for defining if the `id` field of an entity is writable via the -API. Defaults to false. You can set it to `True` if you want to import entities -from another instance and want to keep the `id`. - - -APIS_LIST_VIEWS_ALLOWED ------------------------ - -.. code-block:: python - - APIS_LIST_VIEWS_ALLOWED = False - - -Sets whether list views are accessible for anonymous (not logged in) users. - - -APIS_DETAIL_VIEWS_ALLOWED -------------------------- - -.. code-block:: python - - APIS_DETAIL_VIEWS_ALLOWED - False - - -Sets whether detail views are accessible for anonymous (note logged in) users. - -APIS_VIEW_PASSES_TEST ---------------------- - -Allows to define a function that receives the view as an argument - including -e.g. the `request` object - and can perform checks on any of the views -attributes. The function can, based on these checks, return a boolean which -decides if the request is successful or leads to a 403 permission denied. - -APIS_LIST_VIEW_OBJECT_FILTER ----------------------------- - -Allows to define a function that receives the view - including e.g. the -`request` object - and a queryset and can do custom filtering on that queryset. -This can be used to set the listviews to public using the -`APIS_LIST_VIEWS_ALLOWED` setting, but still only list specific entities. diff --git a/docs/source/user_documentation.rst b/docs/source/user_documentation.rst deleted file mode 100644 index d81dea163..000000000 --- a/docs/source/user_documentation.rst +++ /dev/null @@ -1,45 +0,0 @@ -User documentation -================== - -The user documentation is for researchers that use the system in their day to day work. Developers please refer to the -:doc:`internal_api` and :doc:`data_model`, admins please please refer to :doc:`installation` and :doc:`configuration`. - -finding entities within APIS ----------------------------- - -You can search for the forename or the surname of a person. As a result you will get a list with suitable biographies. -Then you can apply different filters like date of birth or gender to narrow your search down. If you are already working -on a predefined collection you can also select a specific filter to get all biographies linked to it. For every type of -entity the view differs a little bit. For instance you can filter the places also through longitude or latitude -coordinates. Within the institutions you can search for the date of foundation. Etc. - -building own vocabularies -------------------------- - -If you start a new annotation project you will first need to define your vocabularies. It will depend on your particular -research questions and interests. Each vocabulary defines the specific relation between two types of entities -(like person and place, person and person e.g.). For the beginning try to keep it simple and start with a general set -of relations like place of activity, place of study or place of residence. If you get a better understanding of the -biographical narratives in your collection you will be able to build up a more customised vocabulary. There every relation -can be hierarchical structured. That means you can have a relation like was university president of the Universität Wien -which is the subcategory of was employee of Universität Wien. - -editing and deleting relations ------------------------------- - -To come - -highlighting within text ------------------------- - -To come - -visualizing data as a network graph ------------------------------------ - -To come - -exporting data --------------- - -To come \ No newline at end of file