First documentation of usage, configuration build, install

README.md now contains short usage example

Author: hzb-ps

README.md

@@ -1,32 +1,22 @@
-# bact-archiver BACT: access to the archiver appliance
+# bact-archiver: access to the archiver appliance
 
-Build instructions
-------------------
+## Usage
 
-Distribution files contain the files generated by protoc and cython. THus
-standard python build commands are sufficient. If you are using the
-git repository you need to execute described below.
 
+Typically download bact-archiver-local.
+Rename it and configure it as described in the configuration section of this
+package documentation.
 
-Rebuilding generated files
---------------------------
+Then you can use it by
 
-This packages uses the following code generation tools
+```python3
 
-* protoc, the protocl buffer compiler
-* cython, the cython compiler
+from <your-local-bact-archiver-package> import default as default_archiver
+import datetime
 
-To rebuild the files generated by protoc use
-```shell
-> python3 setup.py build_proto_c
-```
-
-To force that the cython generated files are rebuilt use
-```shell
-> CYTHONIZE=1 setup.py
-```
+t0 = datetime.datetime(2020, 11, 20, 7, 40)
+t1 = datetime.datetime(2020, 11, 20, 7, 50)
 
-Finally use the usual build commands:
-```shell
-> python3 setup.py build
+pvname = 'TOPUPCC:rdCur'
+df = default_archiver.getData(pvname, t0=t0, t1=t1)
 ```

doc/bact_archiver.rst

@@ -1,6 +1,18 @@
 bact-archiver package
 =====================
 
+The module :mod:`bact_archiver` provides access to an EPICS appliance
+archiver using the protocol buffer interface.
+
+
+.. toctree::
+
+    bact_archiver_usage
+    bact_archiver_build
+    bact_archiver_config
+    bact_archiver_register
+    bact_archiver.archiver
+
 Module contents
 ---------------
 
@@ -13,4 +25,3 @@ Subpackages
 -----------
 
 .. toctree::
-   bact-archiver.archiver

doc/bact_archiver_build.rst

@@ -0,0 +1,32 @@
+Building the bact archiver package
+==================================
+This packages implements the protobuf based access to the archiver
+appliance. This packages contains:
+
+* In directory `proto`
+
+    * the protocol definition
+    * cython files for the access
+
+
+* In directory `proto_gen`
+
+    * the files generated by the protoc compiler, as long as these
+      need to be compiled (i.e. c++ source and header files)
+
+
+ So a typical build process adheres to standard package interface
+
+Budiling protocol buffer files
+------------------------------
+
+A custom command is provided for the protoc compile step. Please use
+
+.. code::python
+
+   python3 setup.py build_proto_c
+
+
+for this step. This step is typically required to keep track with the locally
+used protobuf implementation. A following build will cythonize and
+compile the generated files.

doc/bact_archiver_config.rst

@@ -1,2 +1,39 @@
 Configuring bact archiver
 =========================
+
+This packages contains the code implementing the protobuf based
+protocol. For adaption to local installation it is recommended
+to create a package like e.g. http:pypi.org//bact-archiver-bessyii.
+
+Apart from files required by setup, this packages contains two files:
+
+    `config/archiver.cfg`
+        access information to the available archivers
+
+    `__init__.py`:
+        executes register function from bact-archiver
+
+
+Format of `config/archiver.cfg`
+-------------------------------
+The default section contains the name of the archivers, that should be
+your default archiver. Apart from the default section, each section
+reflects the access to an archiver appliance. Each entry matches
+one keyword of the initaliser of
+:class:`bact_archiver.config.ArchiverConfiguration`.
+
+
+
+Configuration Classes
+---------------------
+
+.. autoclass:: bact_archiver.config.ArchiverConfigurationInterface
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+.. autoclass:: bact_archiver.config.ArchiverConfiguration
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/bact_archiver_register.rst

@@ -0,0 +1,35 @@
+Registering archivers in your module
+====================================
+
+Typically it will be sufficient to
+
+* edit `config/archiver.cfg`
+
+* leave the following lines in `__init__.py`
+
+
+.. code:: python
+
+    from bact_archiver import register_archivers
+    register_archivers(__name__)
+
+
+if you modify `bact-archiver-local` to your needs. When your packages
+is loaded, :func:`bact_archiver.register_archivers` will read your
+configuration file. It will add each archiver it finds there to your
+module using the `section name` in the configuration. Furthermore it
+will add the default one as 'default'. Thus the default archiver can
+be accessed by `<your-package-name>.default`.
+
+
+Internals of the register module
+--------------------------------
+
+The register module is split up in different parts. These are
+considered internal to the package. Please drop a line if you need
+parts of this functionality exposed.
+
+.. automodule:: bact_archiver.register
+    :members:
+    :undoc-members:
+    :show-inheritance:

doc/bact_archiver_usage.rst

@@ -0,0 +1,19 @@
+Usage
+=====
+
+A typical usage scenario is given below
+
+.. code:: python
+
+    from <your-local-bact-archiver-package> import default as default_archiver
+    import datetime
+
+    t0 = datetime.datetime(2020, 11, 20, 7, 40)
+    t1 = datetime.datetime(2020, 11, 20, 7, 50)
+
+    pvname = 'TOPUPCC:rdCur'
+    df = default_archiver.getData(pvname, t0=t0, t1=t1)
+
+
+if help is required, please address it to the mailing list.
+Examples are very welcomed!