docs: Improve basics and getting started tutorials (#916)

Co-authored-by: Jan Max Meyer <[email protected]>

docs/doc_guide/15_implementation_randomSliceBone.rst

@@ -1,4 +1,3 @@
-
 RandomSliceBone
 ^^^^^^^^^^^^^^^
 
@@ -55,4 +54,4 @@ is two, we've fetched 8 in total). So we can now simply return a random selectio
     In the default configuration of two slices and a sliceSize of 0.5, each request using orderby=random uses 2 times
     more datastore quota than a normal request. This can be reduced to a single db read overhead by setting slices=1
     and sliceSize=0.5. But this also reduces the actual randomness of the entities returned. On the other hand it's
-    possible to increase the randomness by increasing slices and/or sliceSize (which will use up more quota in turn).
+    possible to increase the randomness by increasing slices and/or sliceSize (which will use up more quota in turn).

docs/doc_guide/20_implementation_spatialBone.rst

@@ -1,4 +1,3 @@
-
 SpatialBone
 ^^^^^^^^^^^^
 
@@ -115,7 +114,7 @@ Our algorithm may return points further away, but there might be points in betwe
     :figclass: align-center
 
     Size of the minimum guranteed correctness distance
-    
+
 
 
 

docs/doc_start/05_intro.rst

@@ -31,7 +31,7 @@ ViUR is made for agile software development. The data model can be entirely chan
 
 The system is not only intended to be used by developers. With the use of `Jinja`_ as its template engine for HTML, ViUR is also interesting for designers. A lot of build-in functions, a clear template implementation concept and a collection of macros for data rendering and dynamic input form creation help to connect their creative visions and ideas with a powerful software development framework.
 
-.. _Jinja: http://jinja.pocoo.org/
+.. _Jinja: https://jinja.palletsprojects.com/
 
 =================
 Who created ViUR?

docs/doc_start/10_start.rst

@@ -89,14 +89,18 @@ Starting a ViUR project
 =======================
 
 For a professional project setup, we recommend to use our pre-configured
-`base repository <https://github.com/viur-framework/base>`_. This repository can be used for a ViUR project setup
-that imports the required ViUR modules like *server*, *vi* and *ignite* as submodules into the repository,
-so they can easily be upgraded to newer versions and supplied bugfixes.
+`base repository <https://github.com/viur-framework/viur-base>`_.
+This repository can be used for a ViUR project setup that prepares the required
+ViUR modules like ``viur-core``, ``vi-admin`` and ``ignite`` as dependencies into the repository.
+
 
 ---------------------------
 Cloning the base repository
 ---------------------------
 
+..
+    #TODO: describe the way with the viur-cli!
+
 Simply clone the base repository and afterwards run ``clean-base.py`` to obtain a stand-alone repository which can
 immediately be executed or pushed wherever you like.
 
@@ -105,7 +109,7 @@ These are the commands to be executed in a shell:
 .. code-block:: bash
 
    # Clone base repository into a project folder
-   git clone https://github.com/viur-framework/base.git hello-viur
+   git clone https://github.com/viur-framework/viur-base.git hello-viur
 
    # Change into new project folder
    cd hello-viur

docs/doc_start/20_troubleshooting.rst

@@ -38,7 +38,7 @@ alter your query in a way that excludes these entries. Did you use query.filter(
 perform any error/type-checking. Check that your types match: qry.filter("test =", str("5")) is *not* equivalent to
 qry.filter("test =", int(5)). If in doubt, check the entry, the types of it's values and wherever properties are indexed
 using the cloud console. Temporary rewrite your query to use .mergeExternalFilter() and see if that succeeds.
-If you had still no luck; set "viur.debug.traceQueries" in server.config to True. It will log the raw filters and
+If you had still no luck; set "viur.debug.traceQueries" in viur.core.config to True. It will log the raw filters and
 orderings send to the datastore (and wherever it yields any results). Verify that the query looks like expected, then
 manually run that query in the cloud console using GQL.
 
@@ -68,14 +68,16 @@ Internationalization (i18n) does not work
 -----------------------------------------
 
 Verify that you selected a method for ViUR to determine the language acceptable for the current request
-(check server.config["viur.languageMethod"]). Working with different domains does not work on the development server,
+(check viur.core.config["viur.languageMethod"]). Working with different domains does not work on the development server,
 the session (cookie) approach does not work for search engines like google. Check that your project has a "translations"
 module, it contains tables for the languages you'll need and that it's importable without exception. Then ensure that
-server.config["viur.availableLanguages"] is filled (*after* server.setup() had been called).
+viur.core.config["viur.availableLanguages"] is filled (*after* viur.core.setup() had been called).
 
 
 Still lost?
 -----------
+..
+    #FIXME: Is this still active? How about issues, discussions, ...
 
 Feel free to join our IRC channel #viur on freenode `<https://webchat.freenode.net?channels=viur&uio=d4>`_ and ask your
 project-specific questions.

docs/doc_start/30_myfirstproject.rst

@@ -3,7 +3,7 @@ My first ViUR Project
 #####################
 
 After completing the first steps in the Google Cloud Console you can start programming your first ViUR Application.
-To start, you will need to set up you ViUR system localy.
+To start, you will need to set up you ViUR system locally.
 
 .. warning::
     Before performing the following steps, please make sure to visit `Awesome ViUR <https://awesome.viur.dev>`_
@@ -27,7 +27,7 @@ Start with ViUR
     # The console output should look like this:
     /home/user/.local/bin/viur
 
-3. Create a new local ViUR project for the appengine project you have already created
+3. Create a new local ViUR project for the App Engine project you have already created
 
   .. note::
     If you don't know about this, please revisit "ViUR and the Google Cloud Console"
@@ -37,8 +37,8 @@ Start with ViUR
 
     viur create projectname
 
-  This commmand will prompt you to enter a application name and a develop version name.
-  We recommend naming the application name after your appengine project.
+  This command will prompt you to enter a application name and a develop version name.
+  We recommend naming the application name after your App Engine project.
   The develop version name should be the same, but with a "-dev" postfix.
 
   .. code-block:: bash
@@ -101,7 +101,7 @@ Start with ViUR
 
   .. code-block:: bash
 
-    #This script enables API's and configures some more appengine stuff
+    #This script enables API's and configures some more App Engine stuff
     ./viur-gcloud-setup.sh projectname
 
 8. Try out your installation by running your dev server
@@ -137,11 +137,11 @@ In case you have locked yourself out of your own system. There is a possible way
 all your user data and log ins.
 
 .. warning::
-    All your user data will be deleted in the Appengine and it will not be recoverable.
+    All your user data will be deleted in the App Engine and it will not be recoverable.
     We only recommend this, if you see no other option of logging into your administration system
 
 .. Note::
-    The ViUR-Developers recommmend the usage of a Password Manager
+    The ViUR-Developers recommend the usage of a Password Manager
 
 1. Open https://console.cloud.google.com and navigate to your project
 2. Navigate to the `Datastore Entities Site <https://console.cloud.google.com/datastore/databases/-default-/entities>`_ of your project.

docs/doc_start/index.rst

@@ -1,7 +1,7 @@
 ================================
 Quickstart (the short version)
 ================================
-    1) Ensure that you have Python3.7+, gcloud sdk and git installed
+    1) Ensure that you have Python3.10+, gcloud sdk and git installed
     2) Register a new application-id on https://console.cloud.google.com/
     3) Enable the Firestore in *datastore* mode in this project
     4) Run the following commands
@@ -30,4 +30,4 @@ Getting started
    :maxdepth: 1
    :glob:
 
-   *
+   *

docs/doc_tutorial/advanced/15_training_tasks.rst

@@ -1,4 +1,3 @@
-
 -----
 Tasks
 -----

docs/doc_tutorial/basic/05_training_modulemng.rst

@@ -1,11 +1,10 @@
-
 -----------------
 Module management
 -----------------
 
 In ViUR, any custom modules are established on top of one of the four module prototypes. The modules are the linchpin of every ViUR application. They provide interfaces to securely add, edit, delete or view entries, to perform custom operations and tasks, to prepare output data or validate input data.
 
-The most commonly used module prototype is :class:`List<core.prototypes.list.List>`, which provides a flat list of database entries with the same entity kind. To become more familiar with the management of modules in general, the next sections are mostly using the :class:`~server.prototypes.list.List` module prototype again as its base. Moreover, the other module prototypes and their specialities are discussed later on, when the basics of the :class:`~server.prototypes.list.List` module are understood so far.
+The most commonly used module prototype is :class:`List<core.prototypes.list.List>`, which provides a flat list of database entries with the same entity kind. To become more familiar with the management of modules in general, the next sections are mostly using the :class:`~viur.core.prototypes.list.List` module prototype again as its base. Moreover, the other module prototypes and their specialities are discussed later on, when the basics of the :class:`~viur.core.prototypes.list.List` module are understood so far.
 
 
 Creating modules
@@ -15,10 +14,9 @@ Creating a module is simple. It just requires to put a class named like the new
 
 .. code-block:: python
    :caption: modules/person.py
-   :linenos:
+:linenos:
 
-   #-*- coding: utf-8 -*-
-   from server.prototypes import List
+   from viur.core.prototypes import List
 
    class Person(List):
       pass
@@ -29,7 +27,7 @@ The **class**-statement in line 4 finally introduces the class of the new module
 
 The naming of the class has also two important purposes:
 
-1. The module tries to resolve for a skeleton named after the module in lower-case order with a trailing "Skel" that is used as data model. So in this example, "personSkel" will be the name of the skeleton ViUR will try to resolve. This detection can be completely bypassed, by overriding :meth:`baseSkel<core.prototypes.list.List.baseSkel>` and returning an appropriate skeleton instance.
+1. The module tries to resolve for a skeleton named after the module in lower-case order with a trailing "Skel" that is used as data model. So in this example, "PersonSkel" will be the name of the skeleton ViUR will try to resolve. This detection can be completely bypassed, by overriding :meth:`baseSkel<core.prototypes.list.List.baseSkel>` and returning an appropriate skeleton instance.
 
 2. If the default project setup has been done, the module is automatically imported in lower-case order (person) into the application, so it can be accessed by ``/person`` or ``/renderer/person`` as first part of the URL. This naming convention can be entirely changed by importing the module manually in the file ``modules/__init__.py``.
 

docs/doc_tutorial/basic/10_training_datamng.rst

@@ -10,9 +10,9 @@ Let's start again with the skeleton storing personal data, introduced in the pre
 
 .. code-block:: python
 
-    class personSkel(Skeleton):
-        name = stringBone(descr="Name")
-        age = numericBone(descr="Age")
+    class PersonSkel(Skeleton):
+        name = StringBone(descr="Name")
+        age = NumericBone(descr="Age")
 
 In ViUR, skeletons should be named after modules or usages they are used for. To easily connect a skeleton class with a module, the naming-convention with the trailing "Skel" - like above - should be used, so this is done automatically by the system. Under some circumstances, the name may differ, and can be referenced from the module otherwise, but this is not covered here right now.
 
@@ -41,7 +41,7 @@ To add a data entity with the above skeleton, it first needs to be instantiated.
 .. code-block:: python
 
     # get instance
-    skel = personSkel()
+    skel = PersonSkel()
 
     # set values
     skel["name"] = "Vicky"
@@ -67,7 +67,7 @@ To read an entity directly from the datastore, its key must be known. To do so,
         return
 
     # change something
-    logging.info("Current age of %s is %d" % (skel["name"], skel["age"]))
+    logging.info(f"Current age of {skel['name']} is {skel['age']}")
     skel["age"] = 33
 
     # write entity back again
@@ -97,7 +97,7 @@ To make bones usable within a query, the ``indexed`` attribute of the particular
 .. code-block:: python
    :caption: skeletons/company.py
 
-   class personSkel(Skeleton):
+   class PersonSkel(Skeleton):
       name = stringBone(descr="Name", required=True, indexed=True)
       age = numericBone(descr="Age", indexed=True)
 
@@ -106,15 +106,15 @@ A query can be created from a skeleton using the :meth:`all<core.skeleton.Skelet
 .. code-block:: python
 
     # create the query
-    query = personSkel().all()
+    query = PersonSkel().all()
     query.filter("age >", 30)
 
     # how many result are expected?
     logging.info("%d entities in query" % query.count())
 
     # fetch the skeletons
     for skel in query.fetch():
-        logging.info("%s is %d years old" % (skel["name"], skel["age"]))
+        logging.info(f"{skel['name']} is {skel['age']} years old")
 
 
 Indexes
@@ -126,10 +126,10 @@ Doing so in the following snippet:
 
 .. code-block:: python
 
-    query = personSkel().all().order("name", "age")
+    query = PersonSkel().all().order("name", "age")
 
     for skel in query.fetch():
-        logging.info("%s is %d years old" % (skel["name"].value, skel["age"].value))
+        logging.info(f"{skel['name']} is {skel['age']} years old")
 
 When executed, this yields in the following index definition in the ``index.yaml`` file. The function :meth:`order<core.db.Query.order>`, that was used above, allows to add an ordering on one ore multiple attributes to a query.
 
@@ -157,11 +157,11 @@ The following piece of code is an example for a function that works exactly on t
     @CallDeferred
     def fetchAllPersons(cursor = None):
         # create the query
-        query = personSkel().all().filter("age >", 30).cursor(cursor)
+        query = PersonSkel().all().filter("age >", 30).cursor(cursor)
 
         # fetch the skeletons
         for skel in query.fetch():
-            logging.info("%s is %d years old" % (skel["name"], skel["age"]))
+            logging.info(f"{skel['name']} is {skel['age']} years old")
 
         # if entities where fetched, take the next chunk
         if query.count():
@@ -195,7 +195,7 @@ Let's connect the persons to companies. The figure above shows a classic 1:N rel
 .. code-block:: python
    :caption: skeletons/company.py
 
-    class companySkel(Skeleton):
+    class CompanySkel(Skeleton):
         name = stringBone(descr="Company name", required=True, indexed=True)
 
 To administrate companies also with ViUR, a new module-stub needs to be created.
@@ -205,7 +205,7 @@ Then, the entity kind is connected to the person using a :class:`relationalBone<
 .. code-block:: python
    :caption: skeletons/person.py
 
-    class personSkel(Skeleton):
+    class PersonSkel(Skeleton):
         name = stringBone(descr="Name", required=True, indexed=True)
         age = numericBone(descr="Age", indexed=True)
         company = relationalBone(kind="company", descr="Employed at", required=True)
@@ -214,4 +214,4 @@ This configures the data model to require for a company assignment, so that enti
 
 [screenshot missing]
 
-Althought the datastore is non-relational, offering relations is a fairly complex task. To maintain quick response times, ViUR doesn't immediatelly search and update relations when an entry is updated. Instead, a deferred executed task is kicked off on data changing, which updates all of these relations in the background. Through depending on the current load of the web application, these tasks usually catches up within a few seconds. Within this time, a search by such a relation might return stale results.
+Although the datastore is non-relational, offering relations is a fairly complex task. To maintain quick response times, ViUR doesn't immediatelly search and update relations when an entry is updated. Instead, a deferred executed task is kicked off on data changing, which updates all of these relations in the background. Through depending on the current load of the web application, these tasks usually catches up within a few seconds. Within this time, a search by such a relation might return stale results.