From 6a7d3cb58563277cc6671c0ce05471068cc2f0dd Mon Sep 17 00:00:00 2001
From: Damien Lacoste <damien.lacoste@esrf.fr>
Date: Thu, 3 Sep 2020 09:36:22 +0200
Subject: [PATCH] Updated documentation and changelog

---
 CHANGELOG.md         |   2 +-
 README.md            | 156 ++-----------------------------------------
 doc/README.md        |   4 +-
 doc/build.md         |   4 +-
 doc/configuration.md |   8 ++-
 5 files changed, 15 insertions(+), 159 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2405288..3dcb5ae 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,10 +9,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 
+- Removed public headers as the only needed one is AbstractDB from libhdbpp.
 - Moved some system documentation to hdbpp-timescale-project (the consolidated project).
 - Consolidated remaining build/install instructions into README
 - Modified build system to use fetch libhdbpp and include it when requested. This is an aid to development.
-- Supported LIBHDBPP_PROJECT_BUILD flag, that is injected into the build from hdbpp-timescale-project
 - Made compatible with new libhdbpp (namespace, function and path changes)
 
 ### Removed
diff --git a/README.md b/README.md
index bbcd545..486be0f 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@
     - [Configuration Example](#configuration-example)
   - [License](#license)
 
-HDB++ backend library for the TimescaleDb extenstion to Postgresql. This library is loaded by libhdbpp to archive events from a Tango Controls system. Currently in a pre v1 release phase.
+HDB++ backend library for the TimescaleDb extenstion to Postgresql. This library is used by events subscribers to archive events from a Tango Controls system.
 
 The library requires a correctly configured [TimescaleDb](https://www.timescale.com/) installation. 
 
@@ -62,32 +62,7 @@ Please file the bug reports and feature requests in the issue tracker
 
 ## Building
 
-To build the shared library please read the following.
-
-### Dependencies
-
-The project has two types of dependencies, those required by the toolchain, and those to do the actual build. Other dependencies are integrated directly into the project as submodules. The following thirdparty modules exists:
-
-* libpqxx - Modern C++ Postgresql library (submodule)
-* spdlog - Logging system (submodule)
-* Catch2 - Unit test subsystem (submodule)
-* libhdbpp - Configuration can now fetch [original](https://github.com/tango-controls-hdbpp/libhdbpp) to aid development. See build flags.
-
-#### Toolchain Dependencies
-
-If wishing to build the project, ensure the following dependencies are met:
-
-* CMake 3.11 or higher (for FetchContent)
-* C++14 compatible compiler (code base is using c++14)
-
-#### Build Dependencies
-
-Ensure the development version of the dependencies are installed. These are as follows:
-
-* Tango Controls 9 or higher development headers and libraries
-* omniORB release 4 or higher development headers and libraries
-* libzmq3-dev or libzmq5-dev
-* libpq-dev - Postgres C development library
+For a full reference on building please refer to the [documentation](doc/build.md). This is a small summary of the standard building steps.
 
 ### Building Process
 
@@ -124,93 +99,13 @@ cmake -DPostgreSQL_TYPE_INCLUDE_DIR=/usr/include/postgresql/ ..
 
 This should replace the call to cmake in the previous section.
 
-### Build Flags
-
-The following build flags are available
-
-#### Standard CMake Flags
-
-The following is a list of common useful CMake flags and their use:
-
-| Flag | Setting | Description |
-|------|-----|-----|
-| CMAKE_INSTALL_PREFIX | PATH | Standard CMake flag to modify the install prefix. |
-| CMAKE_INCLUDE_PATH | PATH[S] | Standard CMake flag to add include paths to the search path. |
-| CMAKE_LIBRARY_PATH | PATH[S] | Standard CMake flag to add paths to the library search path |
-| CMAKE_BUILD_TYPE | Debug/Release | Build type to produce |
-
-#### Project Flags
-
-| Flag | Setting | Default | Description |
-|------|-----|-----|-----|
-| BUILD_UNIT_TESTS | ON/OFF | OFF | Build unit tests |
-| BUILD_BENCHMARK_TESTS | ON/OFF | OFF | Build benchmark tests (Forces a Release build) |
-| ENABLE_CLANG | ON/OFF | OFF | Clang code static analysis, readability, and cppcore guideline enforcement |
-| FETCH_LIBHDBPP | ON/OFF | OFF | Enable to have the build fetch and use a local version of libhdbpp |
-| FETCH_LIBHDBPP_TAG | | master | When FETCH_LIBHDBPP is enabled, this is the git tag to fetch |
-
-### Running Tests
-
-#### Unit Tests
-
-The project has extensive unit tests to ensure its functioning as expect. Build the project with testing enabled:
-
-```bash
-mkdir -p build
-cd build
-cmake -DBUILD_UNIT_TESTS=ON ..
-make
-```
-
-To run all unit tests, a postgresql database node is required with the project schema loaded up. There is a default connection string inside test/TestHelpers.hpp:
-
-```
-user=postgres host=localhost port=5432 dbname=hdb password=password
-```
-
-If you run the hdb timescale docker image associated with this project locally then this will connect automatically. If you wish to use a different database, edit the string in test/TestHelpers.hpp.
-
-To run all tests:
-
-```bash
-./test/unit-tests
-```
-
-To look at the available tests and tags, should you wish to run a subset of the test suite (for example, you do not have a postgresql node to test against), then tests and be listed:
+### Running tests and benchmark
 
-```bash
-./bin/unit-tests --list-tests
-```
-
-Or:
-
-```bash
-./bin/unit-tests --list-tags
-```
-
-To see more options for the unit-test command line binary:
-
-```bash
-./bin/unit-tests --help
-```
-
-#### Benchmark Tests
-
-These are a work in progress to explore future optimisation point. If built, they can be run as follows:
-
-```bash
-mkdir -p build
-cd build
-cmake -DBUILD_BENCHMARK_TESTS=ON ..
-make
-```
-
-```bash
-./benchmark/benchmark-tests
-```
+Please refer to the full [documentation](doc/build.md).
 
 ## Installing
 
+For a full reference on installation please refer to the [documentation](doc/install.md). This is a small summary of the standard installation steps.
 All submodules are combined into the final library for ease of deployment. This means just the libhdbpp-timescale.so binary needs deploying to the target system.
 
 ### System Dependencies
@@ -231,47 +126,6 @@ sudo make install
 
 The shared library will be installed to /usr/local/lib on Debian/Ubuntu systems.
 
-## Configuration
-
-### Library Configuration Parameters
-
-Configuration parameters are as follows:
-
-| Parameter | Mandatory | Default | Description |
-|------|-----|-----|-----|
-| libname | true | None | Must be "libhdb++timescale.so" |
-| connect_string | true | None | Postgres connection string, eg user=postgres host=localhost port=5432 dbname=hdb password=password |
-| logging_level | false | error | Logging level. See table below |
-| log_file | false | false | Enable logging to file |
-| log_console | false | false | Enable logging to the console |
-| log_syslog | false | false | Enable logging to syslog |
-| log_file_name | false | None | When logging to file, this is the path and name of file to use. Ensure the path exists otherwise this is an error conditions. |
-
-The logging_level parameter is case insensitive. Logging levels are as follows:
-
-| Level | Description |
-|------|-----|
-| error | Log only error level events (recommended unless debugging) |
-| warning | Log only warning level events |
-| info | Log only warning level events |
-| debug | Log only warning level events. Good for early install debugging |
-| trace | Trace level logging. Excessive level of debug, good for involved debugging |
-| disabled | Disable logging subsystem |
-
-### Configuration Example
-
-Short example LibConfiguration property value on an EventSubscriber or ConfigManager. You will HAVE to change the various parts to match your system:
-
-```bash
-connect_string=user=hdb-user password=password host=hdb-database port=5432 dbname=hdb
-logging_level=debug
-log_file=true
-log_syslog=false
-log_console=false
-libname=libhdb++timescale.so
-log_file_name=/tmp/hdb/es-name.log
-```
-
 ## License
 
 The source code is released under the LGPL3 license and a copy of this license is provided with the code.
diff --git a/doc/README.md b/doc/README.md
index d4368d9..8e6dfc9 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -19,8 +19,8 @@ The overview is in the main project [README](../README.md).
 
 ## DB Schema
 
-* [Schema](db-schema-config) guidelines and setup.
+* [Schema](db-schema-config.md) guidelines and setup.
 
 ## Configuration
 
-* [Configuration](configuration) parameter details.
\ No newline at end of file
+* [Configuration](configuration.md) parameter details.
diff --git a/doc/build.md b/doc/build.md
index 3f64960..d072ab6 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -9,7 +9,7 @@ The project has two types of dependencies, those required by the toolchain, and
 * libpqxx - Modern C++ Postgresql library (Submodule)
 * spdlog - Logging system (Submodule)
 * Catch2 - Unit test subsystem (Submodule)
-* libhdbpp - Part of the hdb++ library loading chain (Modified version of [original](https://github.com/tango-controls-hdbpp/libhdbpp) project. This will be pushed back to the original repository in time)
+* libhdbpp - Header from the hdb++ library loading chain (Modified version of [original](https://github.com/tango-controls-hdbpp/libhdbpp) project. This will be pushed back to the original repository in time)
 
 ### Toolchain Dependencies
 
@@ -133,4 +133,4 @@ make
 
 ```bash
 ./benchmark/benchmark-tests
-```
\ No newline at end of file
+```
diff --git a/doc/configuration.md b/doc/configuration.md
index a35efb0..f7342ad 100644
--- a/doc/configuration.md
+++ b/doc/configuration.md
@@ -1,12 +1,14 @@
 # Configuration
 
+This is the configuration to use for [event subscribers](https://github.com/tango-controls-hdbpp/hdbpp-es) to use this backend
+
 ## Library Configuration Parameters
 
 Configuration parameters are as follows:
 
 | Parameter | Mandatory | Default | Description |
 |------|-----|-----|-----|
-| libname | true | None | Must be "libhdb++timescale.so" |
+| libname | true | None | Must be "libhdb++timescale.so", this parameter is getting deprecated as the backend is enforced during compilation |
 | connect_string | true | None | Postgres connection string, eg user=postgres host=localhost port=5432 dbname=hdb password=password |
 | logging_level | false | error | Logging level. See table below |
 | log_file | false | false | Enable logging to file |
@@ -27,7 +29,7 @@ The logging_level parameter is case insensitive. Logging levels are as follows:
 
 ## Configuration Example
 
-Short example LibConfiguration property value on an EventSubscriber or ConfigManager. You will HAVE to change the various parts to match your system:
+Short example LibConfiguration property value on an EventSubscriber. You will HAVE to change the various parts to match your system:
 
 ```
 connect_string=user=hdb-user password=password host=hdb-database port=5432 dbname=hdb
@@ -37,4 +39,4 @@ log_syslog=false
 log_console=false
 libname=libhdb++timescale.so
 log_file_name=/tmp/hdb/es-name.log
-````
\ No newline at end of file
+````
-- 
GitLab