Merge branch 'feature/manualTechnical' into develop

sphinx/source/technical/api.rst

@@ -6,33 +6,34 @@ API
 Introduction
 ============
 
-This page provides an overview of the OpenAtlas Application Programming
-Interface (`API <https://en.wikipedia.org/wiki/API>`_). An API allows easy
-and controlled access from external sources (e.g. presentation sites or
-analytical tools) to your data. It is human and mashine readable and
-provides different approaches to query your data.
+This page provides an overview of the OpenAtlas API. An (`API <https://en
+.wikipedia.org/wiki/API>`_) allows easy and controlled access to the data
+stored in an OpenAtlas instance from external sources, such as presentation
+sites or analytical tools. The information provided is readable for human and
+machines alike. By using the API data can be queried in several different ways.
 
-The OpenAtlas API tries to follow the
+The development of the OpenAtlas API follows the
 `RESTful <https://restfulapi.net/rest-architectural-constraints/>`_ constraints.
 
-To try out the API first hand at our demo site: https://demo.openatlas.eu/swagger.
-If you have your own OpenAtlas instance just visit <your-domain.eu>/swagger. Be aware
-that the :doc:`/admin/api` has to be set to public at the admin section.
-
+Testing the API is possible via: https://demo.openatlas.eu/swagger.
+Using it with the data from a specific OpenAtlas instance is possible by
+visiting <your-domain.eu>/swagger. Be aware
+that the :doc:`/admin/api` has to be set to public in the admin setting
+section of the instance.
 
 Quick Start Guide
 =================
-The API can be accessed via the OpenAtlas user interface or through URL GET
+The API can be accessed via the OpenAtlas user interface or through an URL GET
 requests.
 
 1. UI access
 ------------
-Each detail view of an entity provide two buttons (JSON and RDF) where the
-formats, in which the entity should be exported, can be selected. If the
-buttons are not visible, please change the **Show API links**
-at the :ref:`display` tab in your :doc:`/tools/profile`.
+Each detail view of an entity provides two buttons (JSON and RDF). Via those
+buttons the format, in which the entity will be exported, can be selected.
+If the buttons are not visible, please change the **Show API links**
+in the :ref:`display` tab of your :doc:`/tools/profile` in the settings.
 
-Through the UI, only a single entity can be accessed.
+By using the UI in this way, only a single entity can be accessed.
 
 .. figure:: api_ui_json.jpg
    :align: center
@@ -44,11 +45,12 @@ Through the UI, only a single entity can be accessed.
 
    Possible RDF API formats
 
+
 2. URL / GET access
 -------------------
 The most common way to communicate with the OpenAtlas API is through GET
-request, either manually from the local browser or with other applications
-following a specific URL schema:
+request. This can be done either manually from the local browser or with other
+applications following a specific URL schema:
 
 .. code-block::
 
@@ -58,29 +60,29 @@ following a specific URL schema:
     https://demo.openatlas.eu/api/0.3/entity/5117
 **Domain**
     Location of the OpenAtlas instance from which information should be
-    retrieved; e.g. https://demo-openatlas.eu/ for the demo version.
+    retrieved, e.g. https://demo-openatlas.eu/ for the demo version
 **API Version**
-    Input without version number leads to the current stable version
+    Input without a version number leads to the current stable version
     (`https://demo.openatlas.eu/api/entity/5117 <https://demo.openatlas.eu/api/entity/5117>`_).
     If another version of the API is to be used, the version number can be
-    specified (demo.openatlas.eu/api/**0.4**/entity/5117). A version overview
-    can be found under point Versioning_.
+    specified (e.g. demo.openatlas.eu/api/**0.4**/entity/5117). A version
+    overview can be found under Versioning_.
 **Endpoints**
     Specific data can be queried by attaching an endpoint
-    (demo.openatlas.eu/api/0.4/**entity**/5117). The information is provided
-    in a human - and machine-readable form. Further information under
-    Endpoints_.
+    (e.g. demo.openatlas.eu/api/0.4/**entity**/5117). The information is
+    provided in a human - and machine-readable form. For further information
+    see Endpoints_.
 **Required path values**
     Must be included to create a valid URL. Different endpoints require
-    different values (demo.openatlas.eu/api/0.4/entity/**5117**. **5117** is
-    an ID as required by the entity endpoint) - all required values are state
-    in **{** **}** at the Endpoints_ definition.
+    different values (e.g. demo.openatlas.eu/api/0.4/entity/**5117**.
+    **5117** is an ID as required by the entity endpoint) - all required
+    values are state in **{** **}** at the Endpoints_ definition.
 **Parameters**
     Used to structure additional information for a given URL. They are added
     to the end of an URL after the "?" symbol
-    (demo.openatlas.eu/api/0.4/entity/5117**?**download=true). All available
-    Parameters can be found under Parameters_. For more general information
-    see this
+    (e.g. demo.openatlas.eu/api/0.4/entity/5117**?**download=true). All
+    available Parameters can be found under Parameters_. For more general
+    information see this
     `article <https://www.botify.com/learn/basics/what-are-url-parameters#:~:text=URL%20parameters%20(also%20known%20as,by%20the%20'%26'%20symbol.>`_.
 
 Versioning
@@ -108,42 +110,47 @@ A **stable** version of the API will be available at all times. In addition,
 warning will be posted in the
 `roadmap <https://redmine.openatlas.eu/projects/uni/roadmap>`_ and
 `release notes <https://redmine.openatlas.eu/projects/uni/news>`_ before
-these versions will be discontinued. **Unstable** versions are currently
-developed, so breaking changes may occur at any time without prior notice.
+a versions is discontinued. **Unstable** versions are currently
+still under development, so breaking changes may occur at any time without
+prior notice.
 
 Endpoints
 =========
 
 Through different endpoints, data can be retrieved from OpenAtlas. Each version
-has an own set of endpoints, be sure to use the right one.
+has an own set of endpoints, make sure to use the correct one.
 
 The current version 0.4 endpoint descriptions are available at:
 
-* `Current OpenAPI specification <https://demo.openatlas.eu/swagger/>`_ at the OpenAtlas demo version
-* `Local OpenAPI specification </swagger>`_: this link is only available if called from a OpenAtlas installation
+* `Current OpenAPI specification <https://demo.openatlas.eu/swagger/>`_ for
+  the OpenAtlas demo version
+* `Local OpenAPI specification </swagger>`_: this link is only available if
+  called from an OpenAtlas instance
 
-The requested information is provided in Linked Places format
-`Linked Places format (LPF) <https://github.com/LinkedPasts/linked-places-format>`_. Alternatively,
+The requested information is provided in the
+`Linked Places format (LPF) <https://github.com/LinkedPasts/linked-places-format>`_.
+Alternatively,
 `GeoJSON <https://datatracker.ietf.org/doc/html/rfc7946>`_, `Linked Open Usable Data <https://linked.art/>`_
-or RDFs, derived from the `Linked Open Usable Data <https://linked.art/>`_ data, can be accessed.
+or RDFs, derived from `Linked Open Usable Data <https://linked.art/>`_
+data, can be accessed.
 
 Parameters
 ==========
 
-With parameters the result of the requested endpoint can be manipulated
-(filtered, searched, sorted, etc.). Each endpoint provide another set of
-parameters which can be used. So please consult the `Endpoints`_ listing for
-more details.
+By using parameters the result of the requested endpoint can be manipulated
+(filtered, searched, sorted, etc.). Each endpoint provides another set of
+parameters which can be used. Consult the `Endpoints`_ list for more details.
 
 Parameters are added to the end of an URL after the "**?**" symbol
 (e.g. demo.openatlas.eu/api/0.4/entity/5117**?download=true**) and are
 connected with the "**&**" sign.
-For more general information on this topic see this
+For more general information on this, see this
 `article <https://www.botify.com/learn/basics/what-are-url-parameters#:~:text=URL%20parameters%20(also%20known%20as,by%20the%20'%26'%20symbol.>`_.
 
-* `Current OpenAPI parameters <https://demo.openatlas.eu/swagger/>`_ at the OpenAtlas demo version
-* `Local OpenAPI parameters </swagger>`_: this link is only available if called from a OpenAtlas installation
-
+* `Current OpenAPI parameters <https://demo.openatlas.eu/swagger/>`_ at the
+  OpenAtlas demo version
+* `Local OpenAPI parameters </swagger>`_: this link is only available if
+  called from an OpenAtlas instance
 
 Error handling
 ==============
@@ -168,15 +175,16 @@ Example:
 
 If an invalid endpoint parameter value e.g. ?sort=kfs instead of ?sort=desc is
 entered, Flask catches this via its own
-`Flask-RESTful <https://flask-restful.readthedocs.io/en/latest/>`_ extension.
-An error message is provided by its own error handler
+`Flask-RESTful <https://flask-restful.readthedocs.io/en/latest/>`_ extension
+and displays an error message provided by its own
 `error handler <https://flask-restful.readthedocs.io/en/latest/reqparse.html#error-handling>`_
 
 Proxy
 =====
 
-If the server is behind a proxy, there are some issues with the RDF export of entities.
-To provide the OpenAtlas API with a proxy server, add following line to **instance/production.py**
+If the server is behind a proxy, issues with the RDF export of entities can
+occur. To provide the OpenAtlas API with a proxy server, add the following
+line to **instance/production.py**
 
 .. code-block:: python
 

sphinx/source/technical/application_structure.rst

@@ -5,7 +5,7 @@ Application Structure
 
 The website's software is written in `Python <https://www.python.org/>`_ and
 uses the `Flask <https://palletsprojects.com/p/flask/>`_ framework.
-Below you find an overview of the file structure:
+Below you can find an overview of the file structure:
 
 * **config** - default configuration
 * **files**:
@@ -24,22 +24,22 @@ Below you find an overview of the file structure:
 * **openatlas**:
 
     * **api**
-    * **database** - the SQL code lives here
+    * **database** - SQL code lives here
     * **display** - display manager and utility functions
-    * **forms** - form manager and other forms related files
+    * **forms** - form manager and other form related files
     * **models** - classes used in the application
     * **static** - the web root containing CSS, JavaScript, layout images,
       etc.
     * **templates** - HTML template files
     * **translations** - source and compiled files for translations
     * **views** - files concerning routing, redirects, etc.
 
-* **sphinx** - source files for the user manual, used with
+* **sphinx** - source files of the user manual, for more details see
   `Sphinx <https://www.sphinx-doc.org/en/master/>`_
 * **test**
 
-To retrace for example a call that was made from a web browser such as
-/entity/15883
+To retrace a call that was made from a web browser (for example
+/entity/15883) the following steps will be executed:
 
 * **openatlas/init.py** is processed and **before_request()** is executed
 * The URL is resolved and a function in **views** is called, in this case
@@ -51,6 +51,6 @@ To retrace for example a call that was made from a web browser such as
 * A template is called from the view, in this case
   **openatlas/templates/entity/view.html**
 * The template may use filters defined in **openatlas/display/util.py**
-  like: some_data|some_filter
+  such as: some_data|some_filter
 
 

sphinx/source/technical/database_structure.rst

@@ -14,10 +14,10 @@ Regarding the database structure, the following PostgreSQL schemas are used:
    * Entities (OpenAtlas class instances)
    * Links (CIDOC property instances)
 
-* **public** - general PostgreSQL functionality, e.g. PostGIS functions
-* **web** - none model data related to the website, e.g.
+* **public** - general PostgreSQL functionality such as PostGIS functions
+* **web** - non-model data related to the website such as:
 
    * website settings (upload size limit, email configuration, ...)
-   * groups, users and their preferences, notes, bookmarks, ...
+   * groups, users, user's preferences, notes, bookmarks, ...
    * image annotations
    * external reference system specifications