Update doc

ocsipersist.opam

@@ -4,8 +4,8 @@ version:      "2.0.0"
 authors:      "The Ocsigen team <dev@ocsigen.org>"
 maintainer:   "Jan Rochel <jan@besport.com>"
 license:      "LGPL-2.1-only with OCaml-LGPL-linking-exception"
-synopsis:     "Persistent key/value storage for OCaml using multiple backends"
-description:  "This is an virtual library defining a unified frontend for a number of key/value storage implementations. Ocsipersist is used pervasively in Eliom/Ocsigen to handle sessions and references. It can be used as an extension for ocsigenserver or as a library. Implementations of the following backends currently exist: DBM, PostgreSQL, SQLite."
+synopsis:     "Persistent key-value storage for OCaml using multiple backends"
+description:  "This is an virtual library defining a unified frontend for a number of key-value storage implementations. Implementations of the following backends currently exist: DBM, PostgreSQL, SQLite."
 
 homepage: "https://github.com/ocsigen/ocsipersist"
 bug-reports: "https://github.com/ocsigen/ocsipersist/issues"

src/dbm/dune

@@ -38,6 +38,7 @@
  (name ocsipersist_dbm_config)
  (public_name ocsipersist-dbm-config)
  (modules ocsipersist_config)
+ (wrapped false)
  (libraries xml-light ocsipersist_dbm ocsigenserver))
 
 ; DBM server:

src/dbm/index.mld

@@ -1,29 +1,19 @@
 {0 ocsipersist-dbm}
 
+DBM backend for Ocsipersist.
+For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}.
+This page describes how to configure the DBM backend.
 The DBM backend uses a server process [ocsidbm].
 
 {1 Using as a library}
-For the API documentation see OPAM package [ocsipersist].
 
-If you are not using Ocsigen Server, you can configure with
-{[
-Ocsipersist_settings.set_delay_loading
-Ocsipersist_settings.set_store
-Ocsipersist_settings.set_ocsidbm
-Ocsipersist_settings.set_error_log_path
-]}
+If you are not using Ocsigen Server's configuration file,
+add library [ocsipersist-dbm.settings] in your Dune file, and
+use module {!Ocsipersist_settings}
+to configure the storage file. 
 
 {1 Using with Ocsigen Server: ocsipersist-dbm-config}
 
-For the API documentation see OPAM package [ocsipersist].
-
-Here we document the configuration options of the ocsigenserver extension.
-All sub-tags of the [extension] tag are optional.
-
-{[
-<extension findlib-package="ocsipersist-dbm-config">
-  <delayloading val="false"/>
-  <store dir="store"/>
-  <ocsidbm name="ocsidbm"/>
-</extension>
-]}
+If you want to configure Ocsipersist-dbm from Ocsigen Server's
+configuration file, use package
+{{:../ocsipersist-dbm-config/Ocsipersist_config/index.html}ocsipersist-dbm-config}.

src/dbm/ocsipersist_config.mli

@@ -0,0 +1,16 @@
+(**
+
+If you are using the DBM backend of Ocsipersist 
+with Ocsigen Server with a configuration file,
+install package [ocsipersist-dbm-config] and
+use the following configuration tags.
+All sub-tags of the [extension] tag are optional.
+
+{@xml[
+<extension findlib-package="ocsipersist-dbm-config">
+  <delayloading val="false"/>
+  <store dir="store"/>
+  <ocsidbm name="ocsidbm"/>
+</extension>
+]}
+*)

src/ocsipersist.mli

@@ -1,6 +1,38 @@
-(** Library (and extension for ocsigenserver) for storing and retrieving
-    key/value data in a persistent manner. This module defines a unified
-    frontend for a number of different backends. *)
+(** Persistent key-value store interface for OCaml.
+    This is an virtual library defining a unified frontend for a number of
+    key-value storage implementations. Implementations of the following backends
+    currently exist: SQLite, DBM, PostgreSQL.
+    You can choose the backend you prefer by installing packages
+    [ocsipersist-sqlite], [ocsipersist-dbm] or [ocsipersist-pgsql].
+    
+    Library [Ocsipersist_settings], provided by each of the backends,
+    contain the configuration options for your stores.
+
+    Packages [ocsipersist-sqlite-config], [ocsipersist-dbm-config] and
+    [ocsipersist-pgsql-config] add the possibility to configure the
+    corresponding backends from Ocsigen Server's configuration file. 
+
+    Ocsipersist is used by Eliom for persistent session storages and references.
+
+    Ocsipersist defines several interfaces:
+    - [Ref] is the simpler the use: it provides persistent references
+    - [Store] is a lower level interface for persistent values
+    - [Polymorphic] is a polymorphic table, using Mahshal
+    - [Functorial] is a typed interface for your own data type
+
+Example of use from the toplevel:
+
+{[
+# #require "lwt_ppx";;
+(* #thread;; if you are using OCaml < 5.0.0 *)
+# #require "ocsipersist-sqlite";;
+# Ocsipersist.init ();;
+# let r = Ocsipersist.Ref.ref ~persistent:"r" 444;;
+val r : int Ocsipersist.Ref.t = <abstr>
+# Lwt_main.run (let%lwt v = Ocsipersist.Ref.get r in print_int v; Lwt.return_unit);;
+444- : unit = ()
+]}
+*)
 
 module Functorial : Ocsipersist_lib.Sigs.FUNCTORIAL
 (** Functorial frontent. Allows for custom (de)serialisation functions, which

src/pgsql/dune

@@ -19,6 +19,7 @@
  (name ocsipersist_pgsql_config)
  (public_name ocsipersist-pgsql-config)
  (modules ocsipersist_config)
+ (wrapped false)
  (libraries xml-light ocsigenserver ocsipersist_pgsql))
 
 (documentation

src/pgsql/index.mld

@@ -1,47 +1,18 @@
 {0 ocsipersist-pgsql}
 
-{1 Using as a library}
-For the API documentation see OPAM package [ocsipersist].
-
-If you are not using Ocsigen Server, you can configure with:
-{[
-Ocsipersist_settings.set_host
-Ocsipersist_settings.set_port
-Ocsipersist_settings.set_database
-Ocsipersist_settings.set_user
-Ocsipersist_settings.set_password
-Ocsipersist_settings.set_connexion_pool_size
-Ocsipersist_settings.set_unix_domain_socket_dir
-]}
+PostgreSQL backend for Ocsipersist.
+For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}.
+This page describes how to configure the PostgreSQL backend.
 
-{1 Using with Ocsigen Server: ocsipersist-psql-config}
-
-For the API documentation see OPAM package [ocsipersist].
+{1 Using as a library}
 
-Here we document the configuration options of the ocsigenserver extension.
-All attributes of the [database] tag are optional.
+If you are not using Ocsigen Server's configuration file,
+add library [ocsipersist-pgsql.settings] in your Dune file, and
+use module {!Ocsipersist_settings}
+to configure the storage file. 
 
-One can either define a host to connect to:
-{[
-<extension findlib-package="ocsipersist-pgsql-config">
-  <database
-     host="localhost"
-     port="3000"
-     user="ocsipersist"
-     password="<secret>"
-     size_conn_pool = "16"
-  />
-</extension>
-]}
+{1 Using with Ocsigen Server: ocsipersist-pgsql-config}
 
-Or a UNIX domain socket:
-{[
-<extension findlib-package="ocsipersist-pgsql-config">
-  <database
-    unix_domain_socket_dir = "pgsql_socket"
-    user="ocsipersist"
-    password="<secret>"
-    size_conn_pool = "16"
-  />
-</extension>
-]}
+If you want to configure Ocsipersist-pgsql from Ocsigen Server's
+configuration file, use package
+{{:../ocsipersist-pgsql-config/Ocsipersist_config/index.html}ocsipersist-pgsql-config}.

src/pgsql/ocsipersist_config.mli

@@ -0,0 +1,33 @@
+(**
+If you are using the PostgreSQL backend of Ocsipersist 
+with Ocsigen Server with a configuration file,
+install package [ocsipersist-pgsql-config] and
+use the following configuration tags.
+All attributes of the [database] tag are optional.
+
+One can either define a host to connect to:
+{@xml[
+<extension findlib-package="ocsipersist-pgsql-config">
+  <database
+     host="localhost"
+     port="3000"
+     user="ocsipersist"
+     password="<secret>"
+     size_conn_pool = "16"
+  />
+</extension>
+]}
+
+Or a UNIX domain socket:
+{@xml[
+<extension findlib-package="ocsipersist-pgsql-config">
+  <database
+    unix_domain_socket_dir = "pgsql_socket"
+    user="ocsipersist"
+    password="<secret>"
+    size_conn_pool = "16"
+  />
+</extension>
+]}
+
+*)

src/sqlite/dune

@@ -19,6 +19,7 @@
  (name ocsipersist_sqlite_config)
  (public_name ocsipersist-sqlite-config)
  (modules ocsipersist_config)
+ (wrapped false)
  (libraries xml-light ocsigenserver ocsipersist_sqlite))
 
 (documentation

src/sqlite/index.mld

@@ -1,22 +1,18 @@
 {0 ocsipersist-sqlite}
+
+SQLite backend for Ocsipersist.
+For the API documentation see OPAM package {{:../ocsipersist/Ocsipersist/index.html}ocsipersist}.
+This page describes how to configure the SQLite backend.
+
 {1 Using as a library}
 
-For the API documentation see OPAM package [ocsipersist].
+If you are not using Ocsigen Server's configuration file,
+add library [ocsipersist-sqlite.settings] in your Dune file, and
+use module {!Ocsipersist_settings} to configure the storage file. 
 
-If you are not using Ocsigen Server, you can configure the storage file with
-{[
-Ocsipersist_settings.set_db_file
-]}
 
 {1 Using with Ocsigen Server: ocsipersist-sqlite-config}
 
-If you are using Ocsipersist with Ocsigen Server with a configuration file,
-install package [ocsipersist-sqlite-config] and
-use the following configuration tags.
-All sub-tags of the [extension] tag are optional.
-
-{[
-<extension findlib-package="ocsipersist-sqlite-config">
-  <database file="data/ocsidb"/>
-</extension>
-]}
+If you want to configure Ocsipersist-sqlite from Ocsigen Server's
+configuration file, use package
+{{:../ocsipersist-sqlite-config/Ocsipersist_config/index.html}ocsipersist-sqlite-config}.

src/sqlite/ocsipersist_config.mli

@@ -0,0 +1,12 @@
+(**
+If you are using the SQLite backend of Ocsipersist with Ocsigen Server
+with a configuration file, install package [ocsipersist-sqlite-config] and
+use the following configuration tags.
+All sub-tags of the [extension] tag are optional.
+
+{@xml[
+<extension findlib-package="ocsipersist-sqlite-config">
+  <database file="data/ocsidb"/>
+</extension>
+]}
+*)