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