Merge branch 'f-merge-doc-changes' into 'main'

Quick main-release of documentation

See merge request !103

.gitlab/merge_request_templates/Default.md

@@ -26,6 +26,7 @@ guidelines](https://gitlab.com/caosdb/caosdb/-/blob/dev/REVIEW_GUIDELINES.md)
 - [ ] All automated tests pass
 - [ ] Reference related issues
 - [ ] Up-to-date CHANGELOG.md (or not necessary)
+- [ ] Up-to-date JSON schema (or not necessary)
 - [ ] Appropriate user and developer documentation (or not necessary)
   - How do I use the software?  Assume "stupid" users.
   - How do I develop or debug the software?  Assume novice developers.

CHANGELOG.md

@@ -4,7 +4,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.10.1] - 2023-02-14
+## [Unreleased] - 2023-?
 
 ### Added
 
@@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 
+- [#315](https://gitlab.indiscale.com/caosdb/src/caosdb-webui/-/issues/315) Made it clear that the demo tour is the best starting point for new users.
+
 ## [0.10.0] - 2022-12-19
 (Florian Spreckelsen)
 

README_SETUP.md

@@ -20,10 +20,10 @@
  *
  * ** end header
 -->
+# Build and install the Web Interface
 
-# Getting Started with the Web Interface 
 Here, we document how to install and build the CaosDB Web Interface. If you are
-only interested in how to use it, please continue [here](tutorials/first_steps.html)
+only interested in how to use it, please continue [here](tutorials/index).
 
 ## Folder Structure
 
@@ -72,7 +72,7 @@ See `build.properties.d/00_default.properties` for more information.
 
 * Run `make clean` to clean up everything.
 
-## Documentation #
+## Build the documentation #
 
 Build documentation in `build/` with `make doc`.
 

src/doc/conf.py

@@ -26,9 +26,9 @@ copyright = '2022, IndiScale GmbH'
 author = 'Daniel Hornung'
 
 # The short X.Y version
-version = '0.10.1'
+version = '0.10.2'
 # The full version, including alpha/beta/rc tags
-release = '0.10.1-SNAPSHOT'
+release = '0.10.2-SNAPSHOT'
 
 
 # -- General configuration ---------------------------------------------------
@@ -41,10 +41,10 @@ release = '0.10.1-SNAPSHOT'
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-#    'sphinx_js',
+    #    'sphinx_js',
     'sphinx.ext.todo',
     "sphinx.ext.autodoc",
-#    'autoapi.extension',
+    #    'autoapi.extension',
     "recommonmark",            # For markdown files.
     "sphinx_rtd_theme",
     'sphinx.ext.intersphinx',
@@ -70,7 +70,7 @@ master_doc = 'index'
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

src/doc/extension/forms.rst

@@ -22,7 +22,7 @@ The following code snippet adds a form to the body of the HTML document.
     const config = {
         name: "my_form",
         fields: [
-            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Record Experiment", required: true },
+            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Experiment", required: true },
             { type: "integer", name: "number", label: "A Number", required: true },
             { type: "date", name: "date", label: "A Date", required: false },
             { type: "text", name: "comment", label: "A Comment", required: false },
@@ -85,7 +85,7 @@ If you intend to call a server-side script, the config has to be changed a litte
     const config = {
         script: "process.py",
         fields: [
-            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Record Experiment", required: true },
+            { type: "reference_drop_down", name: "experiment_id", label: "Experiment", query: "FIND Experiment", required: true },
             { type: "integer", name: "number", label: "A Number", required: true },
             { type: "date", name: "date", label: "A Date", required: false },
             { type: "text", name: "comment", label: "A Comment", required: false },

src/doc/extension/module.md

 # How to add a module to CaosDB WebUI
-The CaosDB WebUI is organized in modules which can easily be added and on a module basis enabled or disabled.
+The CaosDB WebUI is organized in modules which can easily be added and enabled or disabled per module.
 
-There are a few steps necessary to create a new module.
+Only a few steps are necessary to create a new module.
 
 ## Create the module file
 
-Create a new file for each new module. We have the convention, that extensions
-which are optional and should stay that way and also custom extensions for
-special purposes to name the file starting with `ext_`. E.g.
-`ext_flight_preview.js`.
+Create a new file for each new module.  We have the convention that extensions which are optional
+(and also custom extensions for special purposes) are saved in files starting with `ext_`,
+e.g. `ext_flight_preview.js`.
 
-This file should define one function that wraps every thing and which is
+This file should define one function that wraps everything, this function is then
 enabled at the bottom of the file:
 
 ```js

src/doc/extension/query_templates.rst

+===============
+Query shortcuts
+===============
+
 Introduction
 ============
 
@@ -7,11 +11,10 @@ data as query strings which are used frequently. They can be stored and
 reused.
 
 .. figure:: images/shortcut_toolbox.png
-   :alt: The Shortcuts in the Query Panel; Note the Toolbox for in the
-   top right
+   :alt: Shortcuts in the query panel. There is a
+         toolbox for editing shortcuts in the top right.
 
-   The Shortcuts in the Query Panel; Note the Toolbox for in the top
-   right
+   Shortcuts in the query panel. Note the toolbox for editing shortcuts in the top right
 
 There are two ways to integrate query templates into the WebUI:
 
@@ -47,7 +50,7 @@ It now opens a form with two input fields, ``Description`` and
 
    The view to create a new shortcut
 
-See `2.4 <#basic-shortcut>`__ and `2.5 <#advanced-shortcut>`__ for
+See `Basic Shortcut`_ and `Advanced Shortcut`_ for
 further explanation of the components of a Query Shortcut.
 
 Edit the fields and click ``Submit`` for the creation of the new
@@ -177,6 +180,10 @@ Each placeholder *id* must occur only once in both components – if you
 need to use two years in your shortcut you have to use ``{year1}`` and
 ``{year2}`` or any other combinations of placeholder *ids*.
 
+
+Global Shortcuts
+================
+
 Example for global_query_shortcuts.json
 ---------------------------------------
 
@@ -191,7 +198,7 @@ The following example for the file global_query_shortcuts.json would create two
         },
         {
             "description": "Show a table of Experiments for year: {year}",
-            "query": "SELECT date, project, identifier FROM Record Experiment with date in {year}"
+            "query": "SELECT date, project, identifier FROM Experiment with date in {year}"
         }
     ]
 

src/doc/index.rst

@@ -7,16 +7,20 @@ Welcome to the documentation of CaosDB's web UI!
    :caption: Contents:
    :hidden:
 
-   Getting started <getting_started>
+   Manual installation <install>
    Tutorials <tutorials/index>
    Concepts <concepts>
    administration/index.rst
    Extending the UI <extension>
    API <api/index>
 
+.. note::
 
-This documentation helps you to :doc:`get started<getting_started>`, explains the most important
-:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials>`.
+   Go to `demo.indiscale.com <https://demo.indiscale.com>`__ and take the interactive tour to learn
+   how to use LinkAhead's web interface.
+
+This documentation helps you to :doc:`install the web UI <install>`, explains the most important
+:doc:`concepts<concepts>` and offers a range of :doc:`tutorials<tutorials/index>`.
 
 
 Indices and tables

src/doc/tutorials/References_button.png

+../../../References_button.png
\ No newline at end of file

src/doc/tutorials/query.rst

@@ -14,31 +14,31 @@ the webinterface under the respective menu entry.
 
 Let's start with a simple one::
 
-    FIND RECORD MusicalInstrument
+    FIND MusicalInstrument
 
 Most queries simply start with the ``FIND`` keyword and describe what we are
-looking for behind that. The ``RECORD`` keyword denotes that we are only looking
-for Records (and not Files, Properties or RecordTypes). Finally, we provided
-a RecordType name: MusicalInstrument. This means that we will get all Records
-that have this RecordType as parent. Try it out!
+looking for behind that. Then, we provided a RecordType name:
+MusicalInstrument. This means that we will get all Records that have this
+RecordType as parent. Try it out!
 
 Let's look at::
 
-    FIND Guitar
+    FIND ENTITY Guitar
 
-When we leave out the ``RECORD`` keyword, we will get every entity that is a
-Guitar. When you submit this query you should find also a RecordType Guitar
-in the results. Using  ``FIND RecordType Guitar`` would restrict the result to
-only that RecordType.
+When we add the ``ENTITY`` keyword we will get every entity that is a
+Guitar -- also the RecordType, and even a Property with that name if there
+exists one. Using  ``FIND RecordType Guitar`` would restrict the result to
+only that RecordType. And ``FIND RECORD MusicalInstrument`` is just equivalent
+to ``FIND MusicalInstrument``.
 
-Note, that you cannot only provide RecordType names after the ``FIND``, but names
-in general: ``FIND RECORD Nice Guitar``. This will give you a Record with the
+Note, that you can provide not only RecordType names after the ``FIND``, but names
+in general: ``FIND "Nice Guitar"``. This will give you a Record with the
 name "Nice Guitar" (if one exists... and there should be one in the demo instance).
 
 While it does not matter whether you use capital letters or not, the names have to
 be exact. There are two features that make it easy to use names for querying
 in spite of this:
-- You can use "*" to match any string. E.g. ``FIND RECORD Nice*``
+- You can use "*" to match any string. E.g. ``FIND Nice*``
 - After typing three letters, names that start with those three are
 suggested by the auto completion.
 
@@ -64,7 +64,9 @@ result set. In general this looks like::
     FIND <Name> <Property Filter>
 
 Typically, the filter has the form ``<Property> <Operator> <Value>``,
-for example ``length >= 0.7mm``.
+for example ``length >= 0.7mm``. Instead of the ``<Name>`` you can also use one
+of the entity roles, namely ``RECORD``, ``RECORDTYPE``, ``FILE``, ``PROPERY``,
+or ``ENTITY``.
 There are many filters available. You can check the specification for a comprehensive description of
 those. Here, we will only look at the most common examples.
 
@@ -72,7 +74,7 @@ those. Here, we will only look at the most common examples.
 If you only want to assure that Records have a certain Property, without imposing
 constrains on the value, you can use::
 
-   FIND RECORD MusicalInstrument WITH Manufacturer
+   FIND MusicalInstrument WITH Manufacturer
 
 
 Similarly, to what we saw above when using incomplete names, you can use a "*"
@@ -138,6 +140,6 @@ information in a table. A comma separated list of Property names can be provided
 
 Or::
 
-   SELECT quality_factor, report, date FROM  Analysis WHICH REFERENCES A Guitar WITH electric=TRUE
+   SELECT quality_factor, report, date FROM Analysis WHICH REFERENCES A Guitar WITH electric=TRUE