Doc: make accessible the documentation generated by odoc.

[EmileRolley]

This PR fix some errors in documentations markups and simplify the access to the generated documentation.

Changelog

• Fix odoc markups in some .mli files.
• Add the src/index.mld file.
• The make doc command now create a symbolic link from docs/odoc.html to the generated documentation index file. Currently, the only two supported modules are Test_lib and Learnocaml_report.

[erikmd]

Hi @EmileRolley :)
given the recent merges, your PR will needed to be rebased. Will you have the time to do it? no hurry anyway.

BTW, could you elaborate on the third item of your initial post?

The make doc command now create a symbolic link from docs/odoc.html to the generated documentation index file.

In particular, do you have suggestions to increase the availability of the doc? (e.g., I would think of mentioning the make doc command in the Markdown documentation, and/or deploying the doc automatically from the CI, maybe?)

[EmileRolley]

Hi @erikmd,

given the recent merges, your PR will needed to be rebased. Will you have the time to do it? no hurry anyway.

Sure, I'm on it!

BTW, could you elaborate on the third item of your initial post?

I have specified the supported modules, but I'm not sure that's what you were talking about 😕

In particular, do you have suggestions to increase the availability of the doc? (e.g., I would think of mentioning the make doc command in the Markdown documentation, and/or deploying the doc automatically from the CI, maybe?)

Adding a comment about the make doc command in the Markdown documentation seems fine to me. However, updating the CI to deploying it doesn't seem very worth it.. Indeed, this documentation will be mainly used by developers contributing to the learn-ocaml development (which will have already cloned the repo).

[EmileRolley]

I added a note in the howto-setup-exercise-development-environment.md page.

I also resolved conflicts but I must have missed something, indeed, the CI is broken. It seems related to the new ocaml version...
Do you have any idea @AltGr (or @erikmd) of how it can be solved?

[erikmd]

I also resolved conflicts but I must have missed something, indeed, the CI is broken. It seems related to the new ocaml version...
Do you have any idea @AltGr (or @erikmd) of how it can be solved?

Indeed I'm puzzled to see that this run failed while it was very OK during the similar CI run on master…

FTR, the corresponding log was:

+ opam switch create . ocaml-system --deps-only --locked
[NOTE] It seems you have not updated your repositories for a while. Consider updating them with:
       opam update


<><> Installing new switch packages <><><><><><><><><><><><><><><><><><><><><><>
Switch invariant: ["ocaml-system"]
Error:  Could not determine which packages to install for this switch:
  * Incompatible packages:
    - (invariant) -> ocaml-system
    - learn-ocaml -> ocaml-base-compiler = 4.12.0
    You can temporarily relax the switch invariant with `--update-invariant'
…

@AltGr do you have an idea of what's happening?

Side question: I don't know what is OCamlPro's update policy for the Docker Hub repo ocamlpro/ocaml, but I was wondering if the following code line shouldn't be changed to just docker run --rm -i ocamlpro/ocaml:4.12?

learn-ocaml/scripts/static-build.sh

Lines 12 to 13 in 2696f86

	docker run --rm -i \
	ocamlpro/ocaml:4.12-2021-07-25 \

unless you believe it's more stable to keep this image as is, but maybe to run opam update -y? (as suggested above in the log…)

[erikmd]

Hi @EmileRolley, I believe the CI issue you had spotted in this PR is now solved (in master);
but there's now a small conflict, so could you please rebase your PR on the current master?
BTW I also left one comment, for a line that should be removed.

[EmileRolley]

Hi @EmileRolley, I believe the CI issue you had spotted in this PR is now solved (in master);
but there's now a small conflict, so could you please rebase your PR on the current master?
BTW I also left one comment, for a line that should be removed.

Hi @erikmd, it's done.
However, I don't know how to resolve your requested change, indeed, I pushed it after rabasing it with master but it still requested...

[erikmd]

Hi @EmileRolley, thanks a lot for your rebase!

However, I don't know how to resolve your requested change, indeed, I pushed it after rabasing it with master but it still requested...

actually I don't see anymore (in the PR diff) the line that I was talking about, so I guess that's very fine as is!

[erikmd]

Side note: I'm puzzled to see that no CI run seems to be triggered by your last push… maybe an issue from GitHub side?

[EmileRolley]

Side note: I'm puzzled to see that no CI run seems to be triggered by your last push… maybe an issue from GitHub side?

I think it was waiting for me to accept your requested change.

[erikmd]

I dunno… let's tentatively close-then-reopen your PR (as this had worked for restarting the GH workflows for #422 :)