Doc: make accessible the documentation generated by odoc.

.gitignore

@@ -33,3 +33,5 @@ translations/*.pot
 tests/corpuses/*
 
 detect-libs.*
+
+docs/odoc.html

Makefile

@@ -2,6 +2,7 @@ all: static build
 
 DUNE = dune
 DUNE_ARGS = --profile=release
+INDEX_ODOC_PATH = docs/odoc.html
 
 build-deps:
 	opam install . --deps-only --locked
@@ -17,6 +18,7 @@ static:
 .PHONY: doc
 doc:
 	@${DUNE} build ${DUNE_ARGS} @doc
+	ln -sf $(PWD)/_build/default/_doc/_html/index.html ${INDEX_ODOC_PATH}
 
 .PHONY: install
 install: static doc
@@ -84,6 +86,7 @@ clean:
 	@${MAKE} -C static clean
 	-rm -rf www
 	-find . -name "*~" -delete
+	-rm -f ${INDEX_ODOC_PATH}
 
 travis: # From https://stackoverflow.com/questions/21053657/how-to-run-travis-ci-locally
 	BUILDID="build-$$RANDOM";					\

docs/howto-setup-exercise-development-environment.md

@@ -47,55 +47,69 @@ your exercises.
 We assume that the current directory is `$DIR`.
 
 First, clone the current learn-ocaml source tree:
+
 ```
 git clone [email protected]:ocaml-sf/learn-ocaml.git && cd learn-ocaml
 ```
 
 If you do not have a GitHub account, do instead:
+
 ```
 git clone https://github.com/ocaml-sf/learn-ocaml.git && cd learn-ocaml
 ```
 
 Get an opam environment (a.k.a "switch") with the learn-ocaml dependencies
 ready:
+
 ```
 opam switch create . --deps-only --locked
 opam install opam-installer
 eval $(opam env)
 ```
+
 (Alternatively, use `opam install . --deps-only` to install the dependencies in
 your current opam switch, without creating a dedicated one.)
 
 
 Second, compile and install the platform:
+
 ```
 make && make opaminstall
 ```
 
 At this point, you should get a working `learn-ocaml` program in
 your path. Try:
+
 ```
 learn-ocaml --help
 ```
+
 This should open the manpage of the command-line tool to interact
 with the platform.
 
+> **Note for developers:**
+> An API documentation could be partially generated with the `make doc` command.
+> _Currently, the only two supported modules are `Test_lib` and `Learnocaml_report`_.
+
 ## Step 2: Set up a work directory
 
 Now, let us go back to `$DIR` and create a root for the source tree of exercises:
+
 ```
 cd $DIR && cp -fr learn-ocaml/demo-repository my-learn-ocaml-repository
 ```
 
 ## Step 3: Sanity check
 
 Check that your installation works:
+
 ```
 learn-ocaml build --repo my-learn-ocaml-repository
 learn-ocaml serve
 ```
 
 This should output several lines in your terminal ending with:
+
 ```
 Starting server on port 8080
 ```

src/app/learnocaml_common.mli

@@ -122,7 +122,7 @@ val get_state_as_save_file : ?include_reports:bool -> unit -> Save.t
 (** Sync the local save state with the server state, and returns the merged save
     file. The save will be created on the server if it doesn't exist.
 
-    This syncs student {b,content}, but never the reports which are only synched
+    This syncs student {b content}, but never the reports which are only synched
     on "Grade" *)
 val sync: Token.t -> Save.t Lwt.t
 

src/app/learnocaml_config.ml

@@ -5,7 +5,7 @@
  * Learn-OCaml is distributed under the terms of the MIT license. See the
  * included LICENSE file for details.  *)
 
-open Js_of_ocaml
+module Js = Js_of_ocaml.Js
 
 class type learnocaml_config = object
   method enableTryocaml: bool Js.optdef_prop

src/app/learnocaml_config.mli

@@ -5,11 +5,11 @@
  * Learn-OCaml is distributed under the terms of the MIT license. See the
  * included LICENSE file for details.  *)
 
-(* This is not transpiled to learnocaml-static.js, but is an interface
+(** This is not transpiled to learnocaml-static.js, but is an interface
    to the values stored in this file.  It is "statically linked" with
    learnocaml-common.ml. *)
 
-open Js_of_ocaml
+module Js = Js_of_ocaml.Js
 
 class type learnocaml_config = object
   method enableTryocaml: bool Js.optdef_prop

src/dune

@@ -0,0 +1,3 @@
+(documentation
+  (package learn-ocaml)
+  (mld_files index))

src/grader/test_lib.mli

@@ -1001,7 +1001,7 @@ module type S = sig
        argument. Here is a list in alphabetic order of each of them.
 
     {3 ?⁠after}
-       defines a function which is called with the current
+    defines a function which is called with the current
        tested inputs, the student {!type:result} and the solution
        {!type:result} and returns a new report which is concatenated to
        reports built with [~test], [~test_sdtout] and [~test_sdterr].
@@ -1010,14 +1010,14 @@ module type S = sig
        appropriate report. Default value is [fun _ _ _ -> []].
 
     {3 ?before}
-       defines a function called right before the application
+    defines a function called right before the application
        of student function to the current tested inputs. Default value
        is [fun _ -> ()]
 
      For [test_function_<args_nb>] only.
 
     {3 ?before_reference}
-       defines a function called right before the
+    defines a function called right before the
        application of solution function to the current tested
        inputs. This function is called {b before} student function
        evaluation. Default value is [fun _ -> ()].
@@ -1026,7 +1026,7 @@ module type S = sig
        [test_function_<args_nb>_against_solution].
 
     {3 ?before_user}
-       defines a function called right before the
+    defines a function called right before the
        application of student function to the current tested
        inputs. This function is called {b after} solution function
        evaluation. Default value is [fun _ -> ()].
@@ -1035,7 +1035,7 @@ module type S = sig
        [test_function_<args_nb>_against_solution].
 
     {3 ?gen}
-       Number of automatically generated tested inputs. Inputs
+    Number of automatically generated tested inputs. Inputs
        are generated using either sampler defined in the current
        environment or function defined with [~sampler] optional
        argument. By default, [gen] is [max 5 (10 - List.length
@@ -1047,7 +1047,7 @@ module type S = sig
      See {{!Sampler.sampler_sec}Sampler module}.
 
     {3 ?sampler}
-       defines the function used to automatically generated
+    defines the function used to automatically generated
        inputs. If unset, the grading function checks if a sampler is
        defined for each input type in the current environment. Such
        sampler for a type [some-type] must be named [sample_some-type]
@@ -1060,22 +1060,22 @@ module type S = sig
      See {{!Sampler.sampler_sec}Sampler module}.
 
     {3 ?test}
-       defines the function used to compare the output of
+    defines the function used to compare the output of
        student function and the output of solution function. Default
        value is {!Tester.test}.
 
      See {{!Tester.tester_sec}predefined testers and tester builders}.
 
     {3 ?test_sdterr}
-       defines the function used to compare the standard
+    defines the function used to compare the standard
        output produced by student function and the one produced by
        solution function. Default value is {!Tester.io_test_ignore}.
 
      See {{!Tester.io_tester_sec}predefined IO testers and IO tester
        builders}.
 
     {3 ?test_sdtout}
-       defines the function used to compare the standard
+    defines the function used to compare the standard
        error produced by student function and the one produced by
        solution function. Default value is {!Tester.io_test_ignore}.
 
@@ -1094,7 +1094,7 @@ module type S = sig
 
     (** [run_timeout ?time v] executes [v()] under an optional time limit.
         The exceptions raised by [v] are intentionally *not* caught,
-        so the caller is able to catch and get a backtrace, if desired. 
+        so the caller is able to catch and get a backtrace, if desired.
         If given, [time] overrides the global timeout parameter.
     *)
     val run_timeout : ?time:int -> (unit -> 'a) -> 'a

src/index.mld

@@ -0,0 +1,13 @@
+{0 The [learn-ocaml] online platform (engine)}
+
+This contains the documentation for the exposed modules used to build binaries
+forming the engine for the learn-ocaml platform, and the common files.
+
+{1 List of documented modules}
+
+Modules documentation could be found here:
+
+{ul
+	{li {{: Test_lib/index.html} [Test_lib]}}
+	{li {{: Learnocaml_report/index.html} [Learnocaml_report]}}
+}

src/state/learnocaml_data.mli

@@ -210,9 +210,8 @@ module Exercise: sig
       Token.Set.t -> assignments -> (status * Token.Set.t) list
 
     (** Computes the current set of skills from the base list (from Meta.t),
-        using the mutable changes in the Status.skill list. E.g. {[
-          get_skills ~base:meta.Meta.requirements st.skills_prereq
-        ]} *)
+        using the mutable changes in the Status.skill list. E.g.
+        {[get_skills ~base:meta.Meta.requirements st.skills_prereq]} *)
     val get_skills: base:string list -> skill list -> string list
 
     (** The opposite of [get_skills]: retrieves the base from the already
@@ -226,7 +225,8 @@ module Exercise: sig
     val skills_focus: Meta.t -> t -> string list
 
     (** Generates a skill list that can be saved, such that
-        {[get_skills ~base (make_skills ~base l) = l]}.
+        {[get_skills ~base (make_skills ~base l) = l]}
+        .
 
         Remember to call [skills_base] first on the base if you got the
         skills from the meta returned by the server. *)

src/toplevel/learnocaml_toplevel.mli

@@ -53,7 +53,7 @@ type t
      the previous outputs are kept and marked as old
      (see {!Learnocaml_toplevel_output.oldify}). Otherwise, the output console is cleaned.
    @param input_sizing
-     See (!Learnocaml_toplevel_input.sizing}.
+     See {!Learnocaml_toplevel_input.sizing}.
    @param history
      The history storage to use. If none, a new volatile one is created.
    @param display_welcome
@@ -114,7 +114,7 @@ val execute_phrase: t ->
       Tells if answers of the toplevel are to be displayed.
     @param message
       Displays [(* message *)] where the code should have been echoed.
-    @returns
+    @return
        Returns [Success true] whenever the code was correctly
        typechecked and its evaluation did not raise an exception nor
        timeouted and [false] otherwise. *)
@@ -152,7 +152,7 @@ val prerr_string: t -> string -> unit
 val print_html: t -> string -> unit
 
 (** scroll the view to show the last phrase.
-    Calls {!Learnocaml_toplevel_output.scroll. *)
+    Calls {!Learnocaml_toplevel_output.scroll}. *)
 val scroll: t -> unit
 
 (** Execute the content of the input [textarea].

src/toplevel/learnocaml_toplevel_worker_caller.mli

@@ -8,10 +8,12 @@
 
 (** An unified interface for OCaml toplevels running in a Web Worker
     or not. This module signature is very simalar to the signature of
-    {!module:Learnocaml_toplevel_toploop}, except: {ul {- all blocking functions
-    will kill the underlying Web Worker when cancelled; a new worker
-    will be spawned. } {- it uses function of type [string -> unit] as
-    outputs instead of [Format.formatter].}}. *)
+    {!module:Learnocaml_toplevel_toploop}, except:
+      {ul
+      {- all blocking functions will kill the underlying Web Worker when
+        cancelled; a new worker will be spawned. }
+      {- it uses function of type [string -> unit] as outputs instead
+        of [Format.formatter].}} *)
 
 open Toploop_results