DOC: Extended documentation.

See caosdb/customers/lfpb/management#416

DEPENDENCIES.md

-# GENERAL
-
-* >=conan-1.37.2 (e.g. with `pip install conan`)
-* >=cmake-3.13
-* >=gcc-10.2.0 | >=clang-11
-
-# OPTIONAL
-
-* For checking the schema of a json configuration file: >=jsonschema-3.2.0
-
-# BUILD DOCS
-
-* doxygen
-* >=python-3.7
-* >=pip-21.0.1
-* python packages from the `doc/requirements.txt` file.
-
-# BUILD AND RUN TESTS
-
-* >=clang-tidy-11
-* >=gtest-1.10.0
-
-# COVERAGE
-
-* >=gcc-10.2.0
-* >=lcov-1.15
-
-# FORMATTING
-
-* >=clang-formatting-11

DEPENDENCIES.md

+doc/DEPENDENCIES.md
\ No newline at end of file

doc/CMakeLists.txt

@@ -89,12 +89,12 @@ if (DOXYGEN_FOUND)
             VERBATIM
             )
         # Copying files is necessary: https://stackoverflow.com/a/45808534/232888
-		# TODO fix for docs
-		#FILE(COPY
-		#Examples.rst
-		#README_SETUP.md
+		FILE(COPY
+		    Examples.rst
+		    README_SETUP.md
+            DEPENDENCIES.md
             # Tutorial.rst
-			#DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
+			DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
     else ()
         message("Sphinx need to be installed to generate the sphinx documentation")
     endif ()

doc/DEPENDENCIES.md

+# Dependencies #
+
+## General ##
+
+```
+>=conan-1.37.2 (e.g. with `pip install conan`)
+>=cmake-3.13
+>=gcc-10.2.0 | >=clang-11
+```
+
+## Optional ##
+
+* For checking the schema of a json configuration file: `>=jsonschema-3.2.0`
+
+## Build docs ##
+
+```
+doxygen
+>=python-3.7
+>=pip-21.0.1
+python packages from the `doc/requirements.txt` file
+```
+
+## Build and run tests ##
+
+```
+>=clang-tidy-11
+>=gtest-1.10.0
+```
+
+## Coverage ##
+
+```
+>=gcc-10.2.0
+>=lcov-1.15
+```
+
+## Formatting ##
+
+```
+>=clang-formatting-11
+```

doc/Examples.rst

@@ -5,10 +5,10 @@ Examples
 Connect to a CaosDB server
 --------------------------
 
-See also the hints on how to :doc:`get started<README_SETUP>`, and set-up of
-libcaosdb. In order to connect to a CaosDB server with libcaosdb you first have to configure the
-connection via a configuration file as explained in the :ref:`configuration section <Client Configuration>`. Once the configuration is set up, connecting to the server is
-as easy as
+See also the hints on how to :doc:`get started<README_SETUP>`, and set-up of libcaosdb. In order to
+connect to a CaosDB server with libcaosdb you first have to configure the connection via a
+configuration file as explained in the :ref:`"Client Configuration" section <Client
+Configuration>`. Once the configuration is set up, connecting to the server is as easy as
 
 .. code:: cpp
 

doc/README_SETUP.md

@@ -2,11 +2,12 @@
 
 ## Dependencies
 
-* See [DEPENDENCIES.md](Dependencies.md)
+* See the [dependencies](DEPENDENCIES.md) file.
 
 ## Build
 
-We use [cmake](https://cmake.org) as build tool.
+We use [cmake](https://cmake.org) as build tool, with Conan as package manager.  The compiler must support the C++17
+standard.
 
 0. clone/update the subrepo `git submodule update --init proto`
 1. `mkdir build && cd build`
@@ -23,6 +24,10 @@ The default install prefix is `~/.local`. It can be set by adding
 `-DCMAKE_INSTALL_PREFIX=/path/to/install/prefix` to the first cmake
 command (3.).
 
+If you want to build or install libcaosdb without the use of Conan, feel free to rewrite the
+CMakeLists.txt as needed.  The CaosDB project is open to merge requests which support multiple ways
+of installation.
+
 ### How to build on MacOS
 
 Instead of the above conan command (2.) use
@@ -36,7 +41,7 @@ variable.
 
 #### Problems and solutions ####
 
-- Make sure that your conan version supports your XCode version.  A typical symptom of version
+- Make sure that your Conan version supports your XCode version.  A typical symptom of version
   mismatch is for example conan complaining about incompatible `compiler.version` settings.  You may
   need to rerun any conan and cmake commands (and delete cache files first) after compiler updates.
 
@@ -54,7 +59,12 @@ as compiler. We use [cmake](https://cmake.org/download/) as build tool.
    and build the project. (You can open Tools/Command Line/Developer Command
    Prompt and execute `msbuild libcaosdb.sln /property:Configuration=Release`)
 
-### Creating a Local Conan Package ##
+#### Known problems ####
+
+- Linking dynamic libraries currently fails on Windows.  So probably other CaosDB libraries which
+  make use of libcaosdb also will not build.
+
+### Creating a local Conan package ##
 
 Building and installing libcaosdb with Conan is just a single command: `make conan`
 
@@ -62,7 +72,7 @@ For MacOS, you probably should adjust the option as mentioned above.
 
 ### Troubleshooting
 
-#### `conan install` Fails Due to Missing Prebuilts
+#### `conan install` fails due to missing prebuilts
 
 When `conan install` fails during the installation of the dependencies because
 a precompiled package is not available for your specific settings, try adding
@@ -70,8 +80,8 @@ the `--build=missing` option: `conan install .. [ other options
 ] --build=missing`. This should download and compile the sources of the
 dependencies.
 
-#### cmake fails when using the Debug flag
-Depending on the clang version it might be necessary to use additionally the following flag:
+#### cmake fails when using the debug flag
+Depending on the clang version it might be necessary to additionally use the following flag:
 `-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
 
 #### conan uses outdated cppstd during install
@@ -81,9 +91,32 @@ to, e.g., `std::string_view` being unavailable, try specifying the cpp
 standard manually by `conan install .. [other options] -s
 "compiler.cppstd=17"`.
 
-## Unit Tests
+## Client Configuration ##
+
+You can use a json file for the configuration of the client. See
+`test/test_data/test_caosdb_client.json` for an example. You may use
+`caosdb-client-configuration-schema.json` to validate your schema.
+Typically, you will need to provide the path to your SSL certificate.
+
+The client will load the configuration file from the first existing
+file in the following locations (precedence from highest to lowest):
+
+1. A file specified by the environment variable
+   `$CAOSDB_CLIENT_CONFIGURATION`.
+2. `$PWD/caosdb_client.json`
+3. `$PWD/caosdb-client.json`
+4. `$PWD/.caosdb_client.json`
+5. `$PWD/.caosdb-client.json`
+6. `$HOME/caosdb_client.json`
+7. `$HOME/caosdb-client.json`
+8. `$HOME/.caosdb_client.json`
+9. `$HOME/.caosdb-client.json`
+
+## Develop ##
+
+### Unit tests ###
 
-### Build
+#### Build ####
 
 For the tests there is a slightly different setup required (with option `-D CMAKE_BUILD_TYPE=Debug`)
 
@@ -96,15 +129,15 @@ For the tests there is a slightly different setup required (with option `-D CMAK
 	 `-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
 5. `cmake --build .`
 
-### Run
+#### Run ####
 
 In the build directory, run `ctest`
 
-### Framework
+#### Framework ####
 
 We use [GoogleTest](https://google.github.io/googletest/) for unit testing.
 
-### Coverage
+#### Test coverage ####
 
 We use [gcov](https://gcc.gnu.org/onlinedocs/gcc/Gcov.html) and
 [lcov](https://github.com/linux-test-project/lcov) for generating test coverage
@@ -119,39 +152,18 @@ necessary to run `ctest` prior to this target.
 The coverage report can be viewed in a browser by opening
 `<build_directory>/unit_test_coverage/index.html`.
 
-## Code Formatting
+### Code formatting ###
 
 * install clang-format on your system.
 * `clang-format -i --verbose $(find test/ src/ include/ -type f -iname "*.cpp" -o -iname "*.h" -o -iname "*.h.in")`
 
-## Naming Convention
+### Naming conventions ###
 
 Please adhere to [Google's C++ naming conventions](https://google.github.io/styleguide/cppguide.html#Naming).
 
-## Client Configuration
-
-You can use a json file for the configuration of the client. See
-`test/test_data/test_caosdb_client.json` for an example. You may use
-`caosdb-client-configuration-schema.json` to validate your schema.
-Typically, you will need to provide the path to your SSL certificate.
-
-The client will load the configuration file from the first existing
-file in the following locations (precedence from highest to lowest):
-
-1. A file specified by the environment variable
-   `$CAOSDB_CLIENT_CONFIGURATION`.
-2. `$PWD/caosdb_client.json`
-3. `$PWD/caosdb-client.json`
-4. `$PWD/.caosdb_client.json`
-5. `$PWD/.caosdb-client.json`
-6. `$HOME/caosdb_client.json`
-7. `$HOME/caosdb-client.json`
-8. `$HOME/.caosdb_client.json`
-9. `$HOME/.caosdb-client.json`
-
-## Documentation
+### Documentation ###
 
-In the build directory, run
+To build the documentation, run in the build directory
 
 * `cmake --build . --target doc-doxygen` (generate Doxygen)
 * `cmake --build . --target doc-sphinx` (generate Sphinx)

doc/capi/index.rst.in

@@ -21,19 +21,25 @@
 
 .. _capi_root:
 
+=======
  C API
-=====
+=======
+
+.. warning::
+
+   The C API is intended for developers of other libraries.  Special carre needs to be taken for
+   correct memory management.
 
 .. note::
 
-   When working with libcaosdb's C API keep the following in
-   mind. Delete all objects (transactions, entities, properties,
-   parents, ...) that you created using a `caosdb_..._create_...`
-   function or released using a `caosdb_..._release_...` and only
-   those. This means, that any objects set by a `caosdb_..._get_...`
-   function, are managed by another owning object (e.g., a connection
-   object managed by the connection manager) should not be deleted
-   manually.
+   When working with libcaosdb's C API keep the following in mind:
+
+   Delete all objects (transactions, entities, properties, parents, ...) that you created using a
+   call to ``caosdb_..._create_...`` or released using ``caosdb_..._release_...`` and only those.
+
+   Specifically, any objects set by a ``caosdb_..._get_...`` function are managed by another owning
+   object (e.g., a connection object is managed by the connection manager) and thus should not be
+   deleted manually.
 
    The underlying reason is that all C++ objects are realized in the
    Extern C interface as mutable structs containing a void pointer to

doc/cppapi/index.rst.in

@@ -21,8 +21,27 @@
 
 .. _cppapi_root:
 
+=========
  C++ API
-=======
+=========
+
+This is the C++ library for connecting to CaosDB.  If you are interested in code examples, please
+refer to the corresponding :doc:`documentation section<examples.rst>`.
+
+
+A note on thread safety
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Only the components which handle GRPC and server connections are thread-safe, Entity and Transaction
+objects are not thread-safe.  Therefore derived client libraries, such as those for `Julia
+<https://gitlab.indiscale.com/caosdb/src/caosdb-julialib>`_ and `Octave
+<https://gitlab.indiscale.com/caosdb/src/caosdb-octavelib>`_ probably are not thread-safe either.
+
+There is a `known bug <https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/issues/17>`_ which
+may cause a segmentation fault upon program termination, after leaving the ``main`` function, when
+logging is enabled and multiple threads or processes were started.  If this bothers you, turn the
+logging off in the configuration.
+
 
 .. toctree::
     :glob: