diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index a1e46806012540a800917d8e80753b1c28e5d5fb..e2bebee45ccb7a709387dfe275c00d90e8296c6c 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -84,7 +84,7 @@ if (DOXYGEN_FOUND)
sphinx_out
DEPENDS doc-doxygen
Examples.rst
- Install_develop.md
+ Install_develop.rst
FEATURES.md
CHANGELOG.md
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
@@ -94,7 +94,7 @@ if (DOXYGEN_FOUND)
# Copying files is necessary: https://stackoverflow.com/a/45808534/232888
file(COPY
Examples.rst
- Install_develop.md
+ Install_develop.rst
DEPENDENCIES.md
CHANGELOG.md
FEATURES.md
diff --git a/doc/Install_develop.md b/doc/Install_develop.md
deleted file mode 100644
index ebc9aec411d511b11be37b4c0e7e918d9e44ffeb..0000000000000000000000000000000000000000
--- a/doc/Install_develop.md
+++ /dev/null
@@ -1,177 +0,0 @@
-# How to use and develop libcaosdb
-
-## Dependencies
-
-* See the [dependencies](DEPENDENCIES.md) file.
-
-## Build
-
-### Building with `make` ##
-
-Make sure that the dependencies (see above) are fulfilled. On systems which have `make` installed,
-type this in your command line terminal:
-
-```console
-make conan
-```
-
-### Manual build ##
-
-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`
-2. `conan install .. -s "compiler.libcxx=libstdc++11"`
-3. `cmake -B . ..`
-4. `cmake --build .`
-
-You may also want to install libcaosdb system-wide to
-`CMAKE_INSTALL_PREFIX/lib` by
-
-5. `cmake --install .`
-
-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
-
-If you use apple-clang as the compiler: Instead of the above conan command (2.) use
-
-2. `conan install .. -s "compiler.cppstd=17"`
-
-and continue as you would when building on a Linux system. You may
-have to add `build/lib/` (or, alternatively after installation,
-`CMAKE_INSTALL_PREFIX/lib`) to your `DYLD_LIBRARY_PATH` environmental
-variable.
-
-#### Problems and solutions ####
-
-- 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.
-
-### How to build on Windows
-
-We use [Visual Studio 2019](https://visualstudio.microsoft.com/de/vs/features/cplusplus/)
-as compiler. We use [cmake](https://cmake.org/download/) as build tool.
-
-0. clone/update the subrepo `git submodule update --init proto`
-1. `mkdir build`
-2. `cd build`
-3. `conan install .. -g visual_studio -s arch=x86_64 -s build_type=Release -s compiler.toolset=v142 -s compiler.version=16 -s compiler.runtime=MD --build=missing --update`
-4. `cmake -B . ..`
-5. open ` libcaosdb.sln` with Visual Studio, change the buildtype to `Release`
- and build the project. (You can open Tools/Command Line/Developer Command
- Prompt and execute `msbuild libcaosdb.sln /property:Configuration=Release`)
-
-#### Known problems ####
-
-- Linking dynamic libraries currently fails on Windows. So probably other CaosDB libraries which
- make use of libcaosdb also will not build. This is a known bug and we hope to
- fix this in the next release. See
- [#34](https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/issues/34)
-
-### Troubleshooting
-
-#### `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
-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 additionally use the following flag:
-`-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
-
-#### conan uses outdated cppstd during install
-
-If you experience compiler errors during a `conan install` process due
-to, e.g., `std::string_view` being unavailable, try specifying the cpp
-standard manually by `conan install .. [other options] -s
-"compiler.cppstd=17"`.
-
-## 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 ####
-
-For the tests there is a slightly different setup required (with option `-D CMAKE_BUILD_TYPE=Debug`)
-
-1. `mkdir build && cd build/`
-2. `conan install .. ` (with gcc, append ` -s "compiler.libcxx=libstdc++11"`, with apple-clang,
- append ` -s compiler.cppstd=17`)
-3. `cmake -B . -D CMAKE_BUILD_TYPE=Debug ..`
-* If your clang-format version is too old, formatting, linting etc. can be skipped:
- `cmake -B . -D CMAKE_BUILD_TYPE=Debug -D SKIP_LINTING=ON ..`
-* Depending on the clang version it might be necessary to also add
- `-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"`
-5. `cmake --build .`
-
-#### Run ####
-
-In the build directory, run `ctest`
-
-#### Framework ####
-
-We use [GoogleTest](https://google.github.io/googletest/) for unit testing.
-
-#### 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
-reports.
-
-In the build directory, generate the coverage report by running
-`cmake --build . --target unit_test_coverage`.
-
-Note that this special target will run the tests again. Thus it is not
-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 ###
-
-* 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 conventions ###
-
-Please adhere to [Google's C++ naming conventions](https://google.github.io/styleguide/cppguide.html#Naming).
-
-### Documentation ###
-
-To build the documentation, run in the build directory
-
-* `cmake --build . --target doc-doxygen` (generate Doxygen)
-* `cmake --build . --target doc-sphinx` (generate Sphinx)
diff --git a/doc/Install_develop.rst b/doc/Install_develop.rst
new file mode 100644
index 0000000000000000000000000000000000000000..2a882fab45c77a0712220dd27cc182c42450c35b
--- /dev/null
+++ b/doc/Install_develop.rst
@@ -0,0 +1,222 @@
+How to use and develop libcaosdb
+================================
+
+Dependencies
+------------
+
+- See the `dependencies <DEPENDENCIES.md>`__ file.
+
+Build
+-----
+
+Building with ``make``
+~~~~~~~~~~~~~~~~~~~~~~
+
+Make sure that the dependencies (see above) are fulfilled. On systems
+which have ``make`` installed, type this in your command line terminal:
+
+.. code:: console
+
+ make conan
+
+Manual build
+~~~~~~~~~~~~
+
+We use `cmake <https://cmake.org>`__ as build tool, with Conan as
+package manager. The compiler must support the C++17 standard.
+
+1. clone/update the subrepo ``git submodule update --init proto``
+2. ``mkdir build && cd build``
+3. ``conan install .. -s "compiler.libcxx=libstdc++11"``
+4. ``cmake -B . ..``
+5. ``cmake --build .``
+
+You may also want to install libcaosdb system-wide to
+``CMAKE_INSTALL_PREFIX/lib`` by
+
+1. ``cmake --install .``
+
+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.).
+
+.. Note::
+
+ The C++ CaosDB library links against other libraries which are installed by Conan. So if you want
+ to switch to newer versions of those libraries (possible reasons may be security releases or bug
+ fixes), it is not sufficient to update your system libraries, but you have to update your Conan
+ content and then rebuild libcaosdb.
+
+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
+~~~~~~~~~~~~~~~~~~~~~
+
+If you use apple-clang as the compiler: Instead of the above conan
+command (2.) use
+
+1. ``conan install .. -s "compiler.cppstd=17"``
+
+and continue as you would when building on a Linux system. You may have
+to add ``build/lib/`` (or, alternatively after installation,
+``CMAKE_INSTALL_PREFIX/lib``) to your ``DYLD_LIBRARY_PATH``
+environmental variable.
+
+Problems and solutions
+^^^^^^^^^^^^^^^^^^^^^^
+
+- 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.
+
+How to build on Windows
+~~~~~~~~~~~~~~~~~~~~~~~
+
+We use `Visual Studio
+2019 <https://visualstudio.microsoft.com/de/vs/features/cplusplus/>`__
+as compiler. We use `cmake <https://cmake.org/download/>`__ as build
+tool.
+
+1. clone/update the subrepo ``git submodule update --init proto``
+2. ``mkdir build``
+3. ``cd build``
+4. ``conan install .. -g visual_studio -s arch=x86_64 -s build_type=Release -s compiler.toolset=v142 -s compiler.version=16 -s compiler.runtime=MD --build=missing --update``
+5. ``cmake -B . ..``
+6. open ``libcaosdb.sln`` with Visual Studio, change the buildtype to
+ ``Release`` and build the project. (You can open Tools/Command
+ Line/Developer Command Prompt and execute
+ ``msbuild libcaosdb.sln /property:Configuration=Release``)
+
+Known problems
+^^^^^^^^^^^^^^
+
+- Linking dynamic libraries currently fails on Windows. So probably
+ other CaosDB libraries which make use of libcaosdb also will not
+ build. This is a known bug and we hope to fix this in the next
+ release. See
+ `#34 <https://gitlab.indiscale.com/caosdb/src/caosdb-cpplib/-/issues/34>`__
+
+Troubleshooting
+~~~~~~~~~~~~~~~
+
+``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 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 additionally use
+the following flag: ``-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"``
+
+conan uses outdated cppstd during install
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you experience compiler errors during a ``conan install`` process due
+to, e.g., ``std::string_view`` being unavailable, try specifying the cpp
+standard manually by
+``conan install .. [other options] -s "compiler.cppstd=17"``.
+
+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-1:
+
+Build
+^^^^^
+
+For the tests there is a slightly different setup required (with option
+``-D CMAKE_BUILD_TYPE=Debug``)
+
+1. ``mkdir build && cd build/``
+2. ``conan install ..`` (with gcc, append
+ ``-s "compiler.libcxx=libstdc++11"``, with apple-clang, append
+ ``-s compiler.cppstd=17``)
+3. ``cmake -B . -D CMAKE_BUILD_TYPE=Debug ..``
+ - If your clang-format version is too old, formatting, linting etc. can
+ be skipped:
+ ``cmake -B . -D CMAKE_BUILD_TYPE=Debug -D SKIP_LINTING=ON ..``
+ - Depending on the clang version it may be necessary to also add
+ ``-DCMAKE_CXX_FLAGS="-Wno-unused-parameter"``
+4. ``cmake --build .``
+
+Run
+^^^
+
+In the build directory, run ``ctest``
+
+Framework
+^^^^^^^^^
+
+We use `GoogleTest <https://google.github.io/googletest/>`__ for unit
+testing.
+
+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 reports.
+
+In the build directory, generate the coverage report by running
+``cmake --build . --target unit_test_coverage``.
+
+Note that this special target will run the tests again. Thus it is not
+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
+~~~~~~~~~~~~~~~
+
+- 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 conventions
+~~~~~~~~~~~~~~~~~~
+
+Please adhere to `Google’s C++ naming
+conventions <https://google.github.io/styleguide/cppguide.html#Naming>`__.
+
+Documentation
+~~~~~~~~~~~~~
+
+To build the documentation, run in the build directory
+
+- ``cmake --build . --target doc-doxygen`` (generate Doxygen)
+- ``cmake --build . --target doc-sphinx`` (generate Sphinx)