Merge pull request #14 from mbarbin/prepare-release

Prepare release

CHANGES.md

@@ -1,14 +1,11 @@
-## 0.0.6 (unreleased)
-
-### Added
+## 0.0.6 (2024-10-24)
 
 ### Changed
 
-### Deprecated
-
-### Fixed
-
-### Removed
+- Prepare documentation for initial release.
+- Upgrade to `climate.0.1.0`.
+- Make opam files pass opam-repository linting rules.
+- Upgrade Docusaurus.
 
 ## 0.0.5 (2024-09-17)
 

cmdlang-cmdliner-runner.opam

@@ -9,10 +9,10 @@ doc: "https://mbarbin.github.io/cmdlang/"
 bug-reports: "https://github.com/mbarbin/cmdlang/issues"
 depends: [
   "dune" {>= "3.16"}
-  "ocaml" {>= "5.2"}
+  "ocaml" {>= "4.14"}
   "cmdlang" {= version}
   "cmdlang-to-cmdliner" {= version}
-  "cmdliner" {= "1.3.0"}
+  "cmdliner" {>= "1.3.0" & < "1.4"}
   "err" {= version}
   "odoc" {with-doc}
 ]

cmdlang-tests.opam

@@ -13,13 +13,13 @@ depends: [
   "ocamlformat" {with-dev-setup & = "0.26.2"}
   "base" {>= "v0.17" & < "v0.18"}
   "bisect_ppx" {with-dev-setup & >= "2.8.3"}
-  "climate" {>= "0.1.0~preview-0.1"}
+  "climate" {>= "0.1.0~" & < "0.2"}
   "cmdlang" {= version}
   "cmdlang-cmdliner-runner" {= version}
   "cmdlang-to-base" {= version}
   "cmdlang-to-climate" {= version}
   "cmdlang-to-cmdliner" {= version}
-  "cmdliner" {= "1.3.0"}
+  "cmdliner" {>= "1.3.0"}
   "core" {>= "v0.17" & < "v0.18"}
   "core_unix" {>= "v0.17" & < "v0.18"}
   "err" {= version}

cmdlang-to-climate.opam

@@ -9,8 +9,8 @@ doc: "https://mbarbin.github.io/cmdlang/"
 bug-reports: "https://github.com/mbarbin/cmdlang/issues"
 depends: [
   "dune" {>= "3.16"}
-  "ocaml" {>= "5.2"}
-  "climate" {>= "0.1.0~preview-0.1"}
+  "ocaml" {>= "4.14"}
+  "climate" {>= "0.1.0~" & < "0.2"}
   "cmdlang" {= version}
   "odoc" {with-doc}
 ]

cmdlang-to-cmdliner.opam

@@ -9,9 +9,9 @@ doc: "https://mbarbin.github.io/cmdlang/"
 bug-reports: "https://github.com/mbarbin/cmdlang/issues"
 depends: [
   "dune" {>= "3.16"}
-  "ocaml" {>= "5.2"}
+  "ocaml" {>= "4.14"}
   "cmdlang" {= version}
-  "cmdliner" {= "1.3.0"}
+  "cmdliner" {>= "1.3.0" & < "1.4"}
   "odoc" {with-doc}
 ]
 build: [

cmdlang.opam

@@ -9,7 +9,7 @@ doc: "https://mbarbin.github.io/cmdlang/"
 bug-reports: "https://github.com/mbarbin/cmdlang/issues"
 depends: [
   "dune" {>= "3.16"}
-  "ocaml" {>= "5.2"}
+  "ocaml" {>= "4.14"}
   "odoc" {with-doc}
 ]
 build: [

dune-project

@@ -22,7 +22,7 @@
  (synopsis "Declarative Command-line Parsing for OCaml")
  (depends
   (ocaml
-   (>= 5.2))))
+   (>= 4.14))))
 
 (package
  (name err)
@@ -121,20 +121,24 @@
  (synopsis "Convert cmdlang Parsers to cmdliner")
  (depends
   (ocaml
-   (>= 5.2))
+   (>= 4.14))
   (cmdlang
    (= :version))
   (cmdliner
-   (= 1.3.0))))
+   (and
+    (>= 1.3.0)
+    (< 1.4)))))
 
 (package
  (name cmdlang-to-climate)
  (synopsis "Convert cmdlang Parsers to climate")
  (depends
   (ocaml
-   (>= 5.2))
+   (>= 4.14))
   (climate
-   (>= 0.1.0~preview-0.1))
+   (and
+    (>= 0.1.0~)
+    (< 0.2)))
   (cmdlang
    (= :version))))
 
@@ -143,13 +147,15 @@
  (synopsis "A cmdlang runner using cmdliner and err")
  (depends
   (ocaml
-   (>= 5.2))
+   (>= 4.14))
   (cmdlang
    (= :version))
   (cmdlang-to-cmdliner
    (= :version))
   (cmdliner
-   (= 1.3.0))
+   (and
+    (>= 1.3.0)
+    (< 1.4)))
   (err
    (= :version))))
 
@@ -172,7 +178,9 @@
     :with-dev-setup
     (>= 2.8.3)))
   (climate
-   (>= 0.1.0~preview-0.1))
+   (and
+    (>= 0.1.0~)
+    (< 0.2)))
   (cmdlang
    (= :version))
   (cmdlang-cmdliner-runner
@@ -184,7 +192,7 @@
   (cmdlang-to-cmdliner
    (= :version))
   (cmdliner
-   (= 1.3.0))
+   (>= 1.3.0))
   (core
    (and
     (>= v0.17)

lib/cmdlang/src/command.mli

@@ -1,12 +1,66 @@
-(** Declarative Command-line Parsing for OCaml. *)
+(** Declarative Command-line Parsing for OCaml.
+
+    Cmdlang is a library for creating command-line parsers in OCaml. Implemented
+    as an OCaml EDSL, its declarative specification language lives at the
+    intersection of other well-established similar libraries.
+
+    Cmdlang exposes a single module named [Command], which contains the entire
+    API to declare command line parsers.
+
+    Assuming [Cmdlang.Command] to be available in your scope as [Command], the
+    following is a minimalist command that does nothing:
+
+    {[
+      let cmd : unit Command.t =
+        Command.make
+          ~summary:"A command that does nothing"
+          (let open Command.Std in
+           let+ () = Arg.return () in
+           ())
+      ;;
+    ]}
+
+    To get started with this API refers to this
+    {{:https://mbarbin.github.io/cmdlang/docs/tutorials/getting-started/} tutorial}
+    from cmdlang's documentation. *)
 
 (** {1 Utils} *)
 
 module Nonempty_list : sig
+  (** A type to represent lists that are statically known to be non-empty. *)
+
+  (** The way this constructor is defined allows one to use the regular list
+      literal syntax in a context where a non-empty list is expected. For
+      example, the function {!val:Arg.flag} expects a first argument of type
+      [string Nonempty_list.t] and may be used that way:
+
+      {[
+        Arg.flag [ "verbose" ] ~doc:"enable more output"
+      ]}
+
+      The point being that the following would be a type error:
+
+      {[
+        Arg.flag [] ~doc:"enable more output"
+      ]} *)
   type 'a t = 'a Cmdlang_ast.Ast.Nonempty_list.t = ( :: ) : 'a * 'a list -> 'a t
 end
 
+(** {1 Interfaces}
+
+    These interfaces are convenient to use with the {!module:Param} module, so
+    you can apply its helpers to custom modules. For example, if your module
+    [My_enum] implements the {!Enumerated_stringable} interface, then you can
+    build a parser for it with:
+
+    {[
+      Param.enumerated (module My_enum)
+    ]} *)
+
 module type Enumerated_stringable = sig
+  (** An interface for types that have a finite number of inhabitants that all
+      have a canonical string representation. *)
+
   type t
 
   val all : t list
@@ -28,11 +82,11 @@ end
 
 module type Validated_string = sig
   (** An interface for types that can be parsed from strings, with the possibility
-      of parsing failures. This is useful for types that require validation
-      during conversion from string representations.
+      of parsing failures.
 
-      The names [v] and [to_string] were chosen to match the conventions used by
-      some existing libraries, such as [Fpath]. *)
+      This is useful for types that require validation during conversion from
+      string representations. The names [v] and [to_string] were chosen to match
+      the conventions used by some existing libraries, such as [Fpath]. *)
 
   type t
 
@@ -162,7 +216,17 @@ end
 
 (** {1 Let operators}
 
-    For use with the [( let+ )] style. *)
+    For use with the [( let+ )] style:
+
+    {[
+      let cmd : unit Command.t =
+        Command.make
+          ~summary:"A command that does nothing"
+          (let open Command.Std in
+           let+ () = Arg.return () in
+           ())
+      ;;
+    ]} *)
 
 module Std : sig
   include Applicative_syntax with type 'a t := 'a Arg.t
@@ -173,7 +237,16 @@ end
 
 (** {1 Ppx_let}
 
-    For use with the [( let%map_open.Command )] style. *)
+    For use with the [( let%map_open.Command )] style:
+
+    {[
+      let cmd : unit Command.t =
+        Command.make
+          ~summary:"A command that does nothing"
+          (let%map_open.Command () = Arg.return () in
+           ())
+      ;;
+    ]} *)
 
 module Let_syntax : sig
     (** Substituted below. *)

lib/cmdlang_ast/src/ast.mli

@@ -1,3 +1,20 @@
+(** The internal representation for the EDSL used by the cmdlang library.
+
+    Cmdlang doesn't include an execution engine. Instead, Cmdlang parsers are
+    automatically translated to `cmdliner`, `core.command`, or `climate`
+    commands for execution.
+
+    When you use the cmdlang library to define a command-line interface, you are
+    effectively building a value of type [Cmdlang_ast.Ast.Command.t]. It is then
+    converted internally to the targeted backend.
+
+    This module is not meant to be used directly by users of the library.
+    Rather, users use the [Cmdlang.Command] interface which provides a
+    high-level API meant to be ergonomic and user-friendly.
+
+    [Cmdlang_ast] is exposed to allow extending the library with new backends or
+    to write analysis tools, etc. *)
+
 type 'a parse := string -> ('a, [ `Msg of string ]) result
 type 'a print := Format.formatter -> 'a -> unit
 

lib/cmdlang_cmdliner_runner/src/cmdlang_cmdliner_runner.mli

@@ -1,5 +1,13 @@
-(** This is the standard way that is designed with cmdlang, assuming you are
-    using [Err] etc. *)
+(** An opinionated runner for cmdlang parsers using cmdliner as a backend.
+
+    This module provides a default runner that wraps [cmdlang-to-cmdliner] and
+    runs the command under a [Err.protect] block.
+
+    This furnishes a standard way to run cmdlang commands, assuming you are
+    using [Err].
+
+    It is opinionated and adds a few dependencies to your project, such as
+    [Logs] and [Fmt]. *)
 val run
   :  ?exn_handler:(exn -> Err.t option)
   -> unit Cmdlang.Command.t

lib/cmdlang_to_base/src/translate.mli

@@ -1,3 +1,15 @@
+(** Translate cmdlang parsers to core.command. *)
+
+(** {1 Configuration}
+
+    The translation implemented in this module allows some configuration
+    regarding the resulting command that you want to build. The goal of this
+    configuration is to furnish assistance for complex multi-stages migrations from
+    a backend to another.
+
+    It is currently experimental, not well tested or documented, and expected to
+    change in the future. *)
+
 module Config : sig
   type t
 

lib/cmdlang_to_climate/src/translate.mli

@@ -1,3 +1,11 @@
+(** Translate cmdlang parsers to climate.
+
+    The translation to climate is experimental, not well tested or documented,
+    and doesn't support all features of climate. In particular there's currently
+    no support to target the auto-completion features offered by climate. This
+    is an area left for future work. More info
+    {{:https://mbarbin.github.io/cmdlang/docs/explanation/future_plans/} here}. *)
+
 (** {1 Param} *)
 
 val param : 'a Cmdlang.Command.Param.t -> 'a Climate.Arg_parser.conv

lib/cmdlang_to_cmdliner/src/translate.mli

@@ -1,3 +1,5 @@
+(** Translate cmdlang parsers to cmdliner. *)
+
 (** {1 Param} *)
 
 val param : 'a Cmdlang.Command.Param.t -> 'a Cmdliner.Arg.conv