fixed API doc

lib/bioinfo/bistro_bioinfo.mli

@@ -158,7 +158,7 @@ module Ucsc_gb : sig
   val string_of_genome : [< genome] -> string
   val genome_of_string : string -> genome option
 
-  (** {5 Dealing with genome sequences} *)
+  (** {4 Dealing with genome sequences} *)
   class type chromosome_sequences = object
     inherit directory
     method contents : [`ucsc_chromosome_sequences]
@@ -174,12 +174,12 @@ module Ucsc_gb : sig
   val twoBitToFa : twobit pworkflow -> #bed4 pworkflow -> fasta pworkflow
 
 
-  (** {5 Chromosome size and clipping} *)
+  (** {4 Chromosome size and clipping} *)
   val fetchChromSizes : [< genome] -> chrom_sizes pworkflow
   val bedClip : chrom_sizes pworkflow -> (#bed3 as 'a) pworkflow -> 'a pworkflow
 
 
-  (** {5 Conversion between annotation file formats} *)
+  (** {4 Conversion between annotation file formats} *)
   (* val wig_of_bigWig : bigWig file -> wig file *)
   (* val bigWig_of_wig : ?clip:bool -> [< genome] -> wig file -> bigWig file *)
   val bedGraphToBigWig : [< genome] -> bedGraph pworkflow -> bigWig pworkflow
@@ -188,8 +188,8 @@ module Ucsc_gb : sig
     [< genome] ->
     [ `bed3 of bed3 pworkflow | `bed5 of bed5 pworkflow ] ->
     bigBed pworkflow
-  (** {v bedToBigBed v} utility. Fails when given an empty BED file on
-      input. Note that the underlying {v bedToBigBed v} expects BED
+  (** bedToBigBed utility. Fails when given an empty BED file on
+      input. Note that the underlying bedToBigBed expects BED
       files with {i exactly} 3 or 5 columns. *)
 
   val bedToBigBed_failsafe :

lib/bistro.mli

@@ -1,3 +1,28 @@
+(** A library to build scientific workflows.
+
+     This module introduces a type ['a worfklow] that describe a set
+   of inter-dependent steps that will eventually generate a value of
+   type ['a]. Steps may be either command lines to be executed, or
+   OCaml expressions to be evaluated.
+
+     To build shell-based workflows, use the {!module:Shell_dsl}
+   module, that provides a set of combinators to write shell scripts
+   easily. For instance, the following function shows how to create a
+   gzipped file using the output of another workflow: 
+   {[ 
+      let gzip (x : 'a pworkflow) : 'a gz pworkflow = 
+        Workflow.shell ~descr:"unix.gzip" [ 
+          cmd "gzip" [ string "-c" ; dep x ; string ">" dest ]
+        ] 
+   ]}
+
+     Note that a workflow is just a recipe to build some
+   result. Building the workflow won't actually generate anything. In
+   order to run the workflow, you have to run it using an execution
+   engine like the one provided by [bistro.engine].  *)
+
+(** {2 Base types} *)
+
 type 'a workflow
 type 'a path
 type 'a pworkflow = 'a path workflow
@@ -12,6 +37,9 @@ end
 
 type 'a dworkflow = < directory ; contents : 'a > path workflow
 
+
+(** {2 Building shell-based workflow} *)
+
 module Template_dsl : sig
   type template
 
@@ -86,13 +114,15 @@ module Shell_dsl : sig
     ?img:container_image list ->
     ?stdin:template -> ?stdout:template -> ?stderr:template ->
     template list -> command
-  (** Command-line constructor, e.g. [cmd "echo" ~stdout:dest [ string
-      "foo" ]] will generate a shell command like ["echo foo >
-      /some/path"].
-      - @param env specifies a Docker image where to run the command
-      - @param stdin adds a ["< /some/path"] token at the end of the command
-      - @param stdout adds a ["> /some/path"] token at the end of the command
-      - @param stderr adds a ["2> /some/path"] token at the end of the command *)
+  (** Command-line constructor, e.g. 
+        [cmd "echo" ~stdout:dest [ string "foo" ]] 
+      will generate a shell command like 
+        ["echo foo > /some/path"].
+
+      @param env specifies a Docker image where to run the command
+      @param stdin adds a ["< /some/path"] token at the end of the command
+      @param stdout adds a ["> /some/path"] token at the end of the command
+      @param stderr adds a ["2> /some/path"] token at the end of the command *)
 
   val opt : string -> ('a -> template) -> 'a -> template
   (** Command-line option formatting, e.g.: [opt "--output" dep dest]
@@ -117,7 +147,7 @@ module Shell_dsl : sig
   val ( // ) : template -> string -> template
   (** Similar to {!val:Filename.concat}, but with other types. *)
 
-  (** {5 Useful commands} *)
+  (** {4 Useful commands} *)
 
   val mkdir : template -> command
   val mkdir_p : template -> command
@@ -173,10 +203,10 @@ module Workflow : sig
     ?version:int ->
     Shell_dsl.command list -> 'a path workflow
   (** Workflow constructor, taking a list of commands in input. Other arguments are:
-      - @param descr description of the workflow, used for logging
-      - @param mem required memory
-      - @param np maximum number of cores (could be given less at execution)
-      - @param version version number, used to force the rebuild of a workflow *)
+      @param descr description of the workflow, used for logging
+      @param mem required memory
+      @param np maximum number of cores (could be given less at execution)
+      @param version version number, used to force the rebuild of a workflow *)
 
   val pure : id:string -> 'a -> 'a workflow
   val pure_data : 'a -> 'a workflow
@@ -214,7 +244,7 @@ module Private : sig
   val reveal : 'a workflow -> 'a Bistro_internals.Workflow.t
 end
 
-(** {5 File formats} *)
+(** {2 File formats} *)
 
 class type text_file = object
   inherit file

lib/engine/path.mli

@@ -9,7 +9,8 @@ val of_string : string -> t
 val to_string : t -> string
 
 (** [make_relative ~from:dirA dirB] constructs a relative path that
-    can be used to go from [dirA] to [dirB]. @raise
-    [Invalid_argument] if [dirA] is relative. *)
+    can be used to go from [dirA] to [dirB]. 
+
+    @raise [Invalid_argument] if [dirA] is relative. *)
 val make_relative : ?from:string -> string -> t