From 0053f42f97e190e2a313922b043cee799af096f2 Mon Sep 17 00:00:00 2001
From: Timm Fitschen <t.fitschen@indiscale.com>
Date: Sat, 11 Dec 2021 19:35:28 +0100
Subject: [PATCH] DOC: Add FEATURES and CHANGELOG to docs

---
 CHANGELOG.md            | 29 +----------------------------
 FEATURES.md             | 40 +---------------------------------------
 doc/CHANGELOG.md        | 19 +++++++++++++++++++
 doc/CMakeLists.txt      |  4 ++++
 doc/FEATURES.md         | 39 +++++++++++++++++++++++++++++++++++++++
 doc/cppapi/index.rst.in | 14 --------------
 doc/index.rst.in        |  3 +++
 doc/requirements.txt    |  2 +-
 8 files changed, 68 insertions(+), 82 deletions(-)
 mode change 100644 => 120000 CHANGELOG.md
 mode change 100644 => 120000 FEATURES.md
 create mode 100644 doc/CHANGELOG.md
 create mode 100644 doc/FEATURES.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
deleted file mode 100644
index 3bdcb8c..0000000
--- a/CHANGELOG.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Changelog
-
-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.0.13 - Unreleased]
-
-### Added
-
-* New functions getEnumNameFromValue() and getEnumValueFromName().
-* Extern C now supports the full C++ functionalities.
-
-### Changed
-
-* Integer values are 32 bit now.
-
-### Deprecated
-
-### Removed
-
-### Fixed
-
-* #11 - Transaction::GetResultSet() now always returns a valid reference.
-* #25 - Compiles on MacOS with LLVM now.
-
-### Security
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 120000
index 0000000..5202168
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1 @@
+doc/CHANGELOG.md
\ No newline at end of file
diff --git a/FEATURES.md b/FEATURES.md
deleted file mode 100644
index 8ca4a13..0000000
--- a/FEATURES.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Features
-
-This library provides a client for communication with a CaosDB server over the
-CaosDB GRPC-APIs. The client supports
-
-* Transaction of entities and file transmission.
-* Authentication via Username/Password.
-* Secure communication via TLS.
-* Multiple connections with different servers.
-* Logging.
-* File-based configuration.
-
-The core is written in C++ and makes heavy use of object-oriented patterns. It
-results in a c++ library -- libcaosdb.
-
-For using the library in a plain C context, a thin wrapper is included
--- libccaosdb. It wrapps the C++ classes into structs and the member methods
-into functions which operate on the wrapped C++ instances.
-
-Minimal testing executables in C++ and C are included as well, but they only
-serve as just that -- minimal testing.
-
-## CaosDB Entitiy API
-
-This library implements a subset of the CaosDB Entitiy API (caosdb.entity.v1) as a client.
-
-Current limitations: The implementation does not support mixing retrievals with write-transactions.
-
-## CaosDB Info API
-
-This library implements the CaosDB Info API (caosdb.info.v1) as a client without limitations.
-
-## Thread-safety and Concurrency
-
-Currently, the library should not be considered thread-safe.
-
-The `caosdb::transaction::Transaction` class is designed with an with an
-interface ready for concurrent and asyncronous transactions. However, the
-functions are actually implemented in a blocking, synchronous way.
diff --git a/FEATURES.md b/FEATURES.md
new file mode 120000
index 0000000..2135549
--- /dev/null
+++ b/FEATURES.md
@@ -0,0 +1 @@
+doc/FEATURES.md
\ No newline at end of file
diff --git a/doc/CHANGELOG.md b/doc/CHANGELOG.md
new file mode 100644
index 0000000..dfddb70
--- /dev/null
+++ b/doc/CHANGELOG.md
@@ -0,0 +1,19 @@
+# Changelog
+
+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.1.0 - 2021-12-11]
+
+Initial Release.
+
+Please review [FEATURES.md](./FEATURES.md) for an overview of the features of
+this library. Apart from that, the API documentation for
+[C++](https://docs.indiscale.com/caosdb-cpplib/cppapi/index.html) and [plain
+old C](https://docs.indiscale.com/caosdb-cpplib/capi/index.html) specify the
+public API.
+
+Note that this is still a pre-stable release as indicated by the major version
+number. The API is still under development and is likely to change.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 6219cc6..e047833 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -85,6 +85,8 @@ if (DOXYGEN_FOUND)
                 DEPENDS doc-doxygen
                 Examples.rst
                 README_SETUP.md
+                FEATURES.md
+                CHANGELOG.md
             WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
             COMMENT "Generating API documentation with Sphinx"
             VERBATIM
@@ -94,6 +96,8 @@ if (DOXYGEN_FOUND)
             Examples.rst
             README_SETUP.md
             DEPENDENCIES.md
+            CHANGELOG.md
+            FEATURES.md
             # Tutorial.rst
             DESTINATION "${CMAKE_CURRENT_BINARY_DIR}")
     else ()
diff --git a/doc/FEATURES.md b/doc/FEATURES.md
new file mode 100644
index 0000000..8ca4a13
--- /dev/null
+++ b/doc/FEATURES.md
@@ -0,0 +1,39 @@
+# Features
+
+This library provides a client for communication with a CaosDB server over the
+CaosDB GRPC-APIs. The client supports
+
+* Transaction of entities and file transmission.
+* Authentication via Username/Password.
+* Secure communication via TLS.
+* Multiple connections with different servers.
+* Logging.
+* File-based configuration.
+
+The core is written in C++ and makes heavy use of object-oriented patterns. It
+results in a c++ library -- libcaosdb.
+
+For using the library in a plain C context, a thin wrapper is included
+-- libccaosdb. It wrapps the C++ classes into structs and the member methods
+into functions which operate on the wrapped C++ instances.
+
+Minimal testing executables in C++ and C are included as well, but they only
+serve as just that -- minimal testing.
+
+## CaosDB Entitiy API
+
+This library implements a subset of the CaosDB Entitiy API (caosdb.entity.v1) as a client.
+
+Current limitations: The implementation does not support mixing retrievals with write-transactions.
+
+## CaosDB Info API
+
+This library implements the CaosDB Info API (caosdb.info.v1) as a client without limitations.
+
+## Thread-safety and Concurrency
+
+Currently, the library should not be considered thread-safe.
+
+The `caosdb::transaction::Transaction` class is designed with an with an
+interface ready for concurrent and asyncronous transactions. However, the
+functions are actually implemented in a blocking, synchronous way.
diff --git a/doc/cppapi/index.rst.in b/doc/cppapi/index.rst.in
index 97a3658..67e96fa 100644
--- a/doc/cppapi/index.rst.in
+++ b/doc/cppapi/index.rst.in
@@ -29,20 +29,6 @@ This is the C++ library for connecting to CaosDB.  If you are interested in code
 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:
 
diff --git a/doc/index.rst.in b/doc/index.rst.in
index 47b16c9..5828a70 100644
--- a/doc/index.rst.in
+++ b/doc/index.rst.in
@@ -34,5 +34,8 @@ Welcome to |PROJECT_NAME|'s documentation!
     Examples.rst
     cppapi/index
     capi/index
+    Changelog <CHANGELOG>
+    Dependencies <DEPENDENCIES>
+    Features <FEATURES>
 
 * :ref:`genindex`
diff --git a/doc/requirements.txt b/doc/requirements.txt
index 1a306c6..b1fd50d 100644
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -25,4 +25,4 @@ sphinxcontrib-htmlhelp==1.0.3
 sphinxcontrib-jsmath==1.0.1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.4
-urllib3==1.26.4
+urllib3==1.26.7
-- 
GitLab