Modernize module namespace with (include_subdirs qualified)

.ocamlformat

@@ -1,4 +1,4 @@
-version=0.28.1
+version=0.29.0
 parse-docstrings = false
 wrap-comments = false
 break-cases = fit

CHANGES

@@ -1,3 +1,36 @@
+===== 9.0.0~dev =====
+* Module namespace modernization
+** Public modules are now accessed as Os.Session, Os.User, Os.Tips,
+   Os.Mail, Os.Notif, ... instead of the legacy flat Os_xxx prefix.
+   Implemented with (include_subdirs qualified) + (wrapped false)
+   in dune.
+** New ocsigen-start-compat opam package: provides the legacy
+   Os_xxx module names as include-aliases of the new Os.Xxx
+   modules, to ease migration of existing code.
+* PROJECT_NAME_icons.eliom in the distillery template is now
+  parameterised on Eliom.Content.Html.T (the shared signature
+  exposed by Eliom 13) instead of an ad-hoc ICON_HTML signature.
+* Distillery template
+** Renamed from os.pgocaml to os.
+** Source directory renamed back to template.distillery/ (the
+   convention used by ocsigen-start's previous Makefile-based
+   build), and now installed via dune
+   (install (section lib_root) (files (glob_files_rec
+   (template.distillery/* with_prefix eliom/templates/os))))
+   so the template lands at lib/eliom/templates/os/, where
+   eliom-distillery picks it up at the standard location (Eliom
+   13 dropped the per-package eliom-templates/ auto-discovery).
+* Migrated to the new Eliom 13 module names (Eliom.Service,
+  Eliom.Content, Eliom.Common, ...) and to the wrapped
+  ocsigenserver module names (Ocsigen.Server, Ocsigen.Extensions,
+  Ocsigen.Config, Ocsigen_base.Lib, ...).
+* Build system uses ocsigen-dune-rules (gen sub-command).
+* Os.Email: the default email-sending function now pipes an RFC-2822
+  message to the configured mailer ("sendmail" by default) via
+  Lwt_process, instead of printing to stdout. If the mailer is not on
+  PATH, the email is logged to stderr so the application stays usable
+  out of the box. The now-unused [Invalid_mailer] exception is removed.
+
 ===== 7.1.0 (2024-11) =====
 * Compatibility with WASM
 

README.md

@@ -46,3 +46,23 @@ To get started, take a look at the generated README.md.
 
 You have also the complete manual and API available on
 the [Ocsigen website](http://ocsigen.org/ocsigen-start/)
+
+### Generating API documentation
+
+Wiki API pages are generated from the `.eliomi` and `.mli` files using
+`eliomdoc` and the [wikidoc](https://github.com/ocsigen/wikidoc) plugin:
+
+```bash
+bash build/gen_wikidoc.sh        # all (server + client)
+bash build/gen_wikidoc.sh server # server side only
+bash build/gen_wikidoc.sh client # client side only
+```
+
+Output goes to `_build/doc/dev/api/{server,client}/`.
+
+The wiki files are published on the [wikidoc branch] under
+`doc/dev/api/{server,client}/`. To update the published documentation,
+copy the generated `.wiki` files to a checkout of the `wikidoc` branch
+and commit.
+
+[wikidoc branch]: https://github.com/ocsigen/ocsigen-start/tree/wikidoc/doc/dev/api

build/gen_wikidoc.sh

@@ -0,0 +1,96 @@
+#!/bin/sh
+# Generate wiki API documentation using eliomdoc + wikidoc plugin.
+# Usage: ./build/gen_wikidoc.sh [server|client|all]
+#
+# Output goes to _build/doc/dev/api/{server,client}/.
+# To publish, copy the generated wikis to the matching directories on
+# the [wikidoc] branch.
+
+set -e
+
+WIKIDOC_DIR=$(ocamlfind query wikidoc)
+
+gen_doc() {
+  SIDE="$1"
+
+  case "$SIDE" in
+    server)
+      CMI_DIR=_build/default/src/.ocsigen_start_server.objs/byte
+      DUNE_DIR=src
+      PACKAGES=eliom.server,calendar,ocsigenserver,ocsipersist,pgocaml,pgocaml_ppx,macaddr,yojson,ocsigen-toolkit.server,resource-pooling
+      # Server side: both .eliomi (shared) and .mli (server-only)
+      SOURCE_FILES=$(ls src/Os/*.eliomi src/Os/*.mli 2>/dev/null)
+      ;;
+    client)
+      CMI_DIR=_build/default/src/client/.ocsigen_start_client.objs/byte
+      DUNE_DIR=src/client
+      PACKAGES=eliom.client,calendar,ocsigen-toolkit.client,js_of_ocaml,js_of_ocaml-lwt
+      # Client side: only .eliomi (shared); .mli files are server-only
+      SOURCE_FILES=$(ls src/Os/*.eliomi 2>/dev/null)
+      ;;
+    *)
+      echo "Unknown side: $SIDE"; exit 1
+      ;;
+  esac
+
+  dune build @check 2>/dev/null || true
+
+  INCLUDES=$(dune ocaml dump-dot-merlin "$DUNE_DIR" 2>/dev/null \
+    | grep "^B " | sed 's/^B /-I /' | tr '\n' ' ')
+  JSOO=$(ocamlfind query js_of_ocaml 2>/dev/null || true)
+  [ -n "$JSOO" ] && INCLUDES="$INCLUDES -I $JSOO"
+
+  TMPDIR=$(mktemp -d)
+  trap "rm -rf $TMPDIR" EXIT
+
+  echo "Creating module aliases for ocamldoc..."
+  for cmi in "$CMI_DIR"/os__*.cmi; do
+    [ -f "$cmi" ] || continue
+    base=$(basename "$cmi" .cmi)                   # os__Session
+    short=$(echo "$base" | sed 's/^os__//')        # Session
+    modname=$(echo "${base}" | sed 's/^./\U&/')    # Os__Session
+    echo "include ${modname}" > "$TMPDIR/${short}.ml"
+  done
+  for pass in 1 2 3 4; do
+    compiled=0
+    for ml in "$TMPDIR"/*.ml; do
+      [ -f "$ml" ] || continue
+      short=$(basename "$ml" .ml)
+      if [ ! -f "$TMPDIR/${short}.cmi" ]; then
+        if eval ocamlfind ocamlc -package "$PACKAGES" -c -I "$CMI_DIR" -I "$TMPDIR" $INCLUDES \
+          -o "$TMPDIR/${short}.cmo" "$ml" 2>/dev/null; then
+          compiled=$((compiled + 1))
+        fi
+      fi
+    done
+    [ "$compiled" -eq 0 ] && break
+  done
+  echo "  total: $(ls "$TMPDIR"/*.cmi 2>/dev/null | wc -l) cmi files"
+
+  OUTDIR=_build/doc/dev/api/$SIDE
+  rm -rf "$OUTDIR"
+  mkdir -p "$OUTDIR"
+
+  echo "Generating $SIDE wiki documentation..."
+  eval eliomdoc -"$SIDE" -ppx \
+    -colorize-code -stars -sort \
+    -package "$PACKAGES" \
+    -I "$TMPDIR" \
+    -I "$CMI_DIR" \
+    $INCLUDES \
+    -i "$WIKIDOC_DIR" \
+    -g odoc_wiki.cma \
+    -d "$OUTDIR" \
+    -intro "doc/$SIDE.indexdoc" \
+    -subproject "$SIDE" \
+    $SOURCE_FILES
+
+  echo "Done: $OUTDIR/"
+  echo "  $(ls "$OUTDIR"/*.wiki 2>/dev/null | wc -l) wiki files"
+}
+
+case "${1:-all}" in
+  server|client) gen_doc "$1" ;;
+  all) gen_doc server; gen_doc client ;;
+  *) echo "Usage: $0 [server|client|all]"; exit 1 ;;
+esac

doc/client.indexdoc

@@ -0,0 +1,57 @@
+{1 Ocsigen Start client API}
+
+{2 User management}
+
+{!modules:
+User
+User_view
+User_proxy
+Current_user
+Session
+Connect_phone
+}
+
+{2 Persistence}
+
+{!modules:
+Types
+Email
+}
+
+{2 Notifications}
+
+{!modules:
+Notif
+Msg
+Fcm_notif
+}
+
+{2 Web pages and services}
+
+{!modules:
+Page
+Services
+Handlers
+Icons
+Tips
+Uploader
+Request_cache
+}
+
+{2 Real-time}
+
+{!modules:
+Comet
+}
+
+{2 Utilities}
+
+{!modules:
+Lib
+Date
+Platform
+}
+
+{2 Indexes}
+
+{!indexlist}

doc/intro.mld

@@ -162,80 +162,80 @@ starting guide. Look around!
 Various modules for producing icons, messages, custom pages, tips,
 connection forms, etc.
 
-- {!Os_icons}:
+- {!Os.Icons}:
   manage CSS icons.
-- {!Os_msg}:
+- {!Os.Msg}:
   write messages in the browser console.
-- {!Os_page}:
+- {!Os.Page}:
   utilities for building HTML pages that follow the standard Ocsigen
   Start layout.
-- {!Os_tips}:
+- {!Os.Tips}:
   display tips to the user.
-- {!Os_user_view}:
+- {!Os.User_view}:
   functions for creating password forms and other common UI elements
   appearing in applications and for managing the user connection box.
-- {!Os_uploader}:
+- {!Os.Uploader}:
   ImageMagick-based tools for manipulating avatars.
 
 {2 Users and groups}
 
-- {!Os_user},
-  {!Os_current_user},
-  {!Os_group}:
+- {!Os.User},
+  {!Os.Current_user},
+  {!Os.Group}:
   manage users and groups thereof.
 
-- {!Os_db}:
+- {!Os.Db}:
   directly access the database. In many cases, it is a better idea to
   use higher-level modules (e.g.,
-  {!Os_user}).
+  {!Os.User}).
 
-- {!Os_types}:
-  core types shared by {!Os_db}
+- {!Os.Types}:
+  core types shared by {!Os.Db}
   and the higher-level modules.
 
 {2 Communication}
 
-- {!Os_notif}:
+- {!Os.Notif}:
   send notifications to connected users.
 
-- {!Os_email}:
+- {!Os.Email}:
   send e-mails.
 
-- {!Os_fcm_notif}:
+- {!Os.Fcm_notif}:
   send push notifications to mobile devices.
 
-- {!Os_comet}:
+- {!Os.Comet}:
   manage the bi-directional communication channel between client and
   server. This is a low-level module that you probably don't need.
 
 {2 Services, handlers, sessions}
 
-- {!Os_services}:
+- {!Os.Services}:
   Eliom services pre-defined by Ocsigen Start. These produce the
   default user interface of the template.
   See {{!/eliom/page-"server-services"}the Eliom manual page on services} for
   a general introduction to Eliom services.
 
-- {!Os_handlers}:
+- {!Os.Handlers}:
   The handlers (functions) that implement the services in
-  {!Os_services}.
+  {!Os.Services}.
   {{!/eliom/page-"server-outputs"}The Eliom manual page on service handlers}
   explains how to implement handlers.
 
-- {!Os_session}:
+- {!Os.Session}:
   manage user sessions, e.g., execute actions when users connect or
   disconnect.
 
 {2 Other utilities}
 
-- {!Os_date}:
+- {!Os.Date}:
   utilities for manipulating date and time values.
 
-- {!Os_platform}:
+- {!Os.Platform}:
   obtain information about the platform we are on (Android, iOS, ...).
 
-- {!Os_request_cache},
-  {!Os_user_proxy}:
+- {!Os.Request_cache},
+  {!Os.User_proxy}:
   different forms of caching data.
 
 - A {e ppx} syntax extension to implement RPC.

doc/server.indexdoc

@@ -0,0 +1,60 @@
+{1 Ocsigen Start server API}
+
+{2 User management}
+
+{!modules:
+User
+User_view
+User_proxy
+Current_user
+Group
+Session
+Connect_phone
+}
+
+{2 Persistence}
+
+{!modules:
+Db
+Core_db
+Types
+Email
+}
+
+{2 Notifications}
+
+{!modules:
+Notif
+Msg
+Fcm_notif
+}
+
+{2 Web pages and services}
+
+{!modules:
+Page
+Services
+Handlers
+Icons
+Tips
+Uploader
+Request_cache
+}
+
+{2 Real-time}
+
+{!modules:
+Comet
+}
+
+{2 Utilities}
+
+{!modules:
+Lib
+Date
+Platform
+}
+
+{2 Indexes}
+
+{!indexlist}