Try to fix the #526 documentation issue

[erikmd]

• Kind: bugfix for documentation

Try to Fix #526 (#526 (comment))

Description

Cc @AltGr

I tried solving the "unknown lib" issue in https://ocaml.org/p/learn-ocaml/1.0.0/doc/Test_lib/index.html
by adding (public_name learn-ocaml.test_lib) and (public_name learn-ocaml.report) in the src/grader/dune file.

however, this addition recursively required setting several dune stanzas as public libraries (see last commit),
and ultimately, we end up with the following error:

$ make doc
File "src/grader/dune", line 9, characters 31-42:
9 |  (libraries json-data-encoding ocplib_i18n)
                                   ^^^^^^^^^^^
Error: Library "ocplib_i18n" is private, it cannot be a dependency of a
public library. You need to give "ocplib_i18n" a public name.
File "src/grader/dune", line 198, characters 12-23:
198 |             ocplib_i18n
                  ^^^^^^^^^^^
Error: Library "ocplib_i18n" is private, it cannot be a dependency of a
public library. You need to give "ocplib_i18n" a public name.
make: *** [Makefile:29: doc] Error 1            

To sum, there were three issues to solve:

• Issue 1: the library learn-ocaml.test_lib does not seem to be defined currently,
  despite what is promised at this line:
  

  learn-ocaml/src/grader-plugins/dune

  Line 9 in c8174f8

  ;; (libraries learn-ocaml.test_lib)

  
  as a result, the published documentation says "undefined lib"
• Issue 2: the two pages of the published documentation 1 and 2 do not include any ocamldoc comment, I dunno why.
• Issue 3: the doc. home page does not mention Mutation_test → this is now fixed thanks to bd79ffe updating the index.mld file.

I suspect that the list of all the modules we'd like to document is here:

learn-ocaml/src/grader/test_lib/dune

Lines 21 to 29 in c8174f8

	(ty.cmi as test_lib/ty.cmi)
	(fun_ty.cmi as test_lib/fun_ty.cmi)
	;; (exercise_init.cmi as test_lib/exercise_init.cmi)
	(introspection_intf.cmi as test_lib/introspection_intf.cmi)
	(learnocaml_internal.cmi as test_lib/learnocaml_internal.cmi)
	(pre_test.cmi as test_lib/pre_test.cmi)
	(learnocaml_report.cmi as test_lib/learnocaml_report.cmi)
	(learnocaml_callback.cmi as test_lib/learnocaml_callback.cmi)
	(test_lib.cmi as test_lib/test_lib.cmi))

and that it might suffice to tweak these stanzas:

learn-ocaml/src/grader/dune

Lines 11 to 15 in c8174f8

	(rule
	(targets learnocaml_report.odoc)
	(deps .learnocaml_report.objs/byte/learnocaml_report.cmti)
	(action (run odoc compile --package learn-ocaml %{deps} -o %{targets}))
	)

learn-ocaml/src/grader/dune

Lines 60 to 64 in c8174f8

	(rule
	(targets test_lib.odoc)
	(deps .testing_dyn.objs/byte/test_lib.cmti)
	(action (run odoc compile --package learn-ocaml %{deps} -o %{targets}))
	)

but currently I'm stuck, @AltGr can you take a look?

Checklist

• Read the CONTRIBUTING.md guide and:
  • Use Atomic Commits so each commit gathers a single logical change
  • Use Conventional Commits regarding commit messages (needed by our release toolchain)
• Add/update tests
• Add/update documentation
• …

Note to maintainers

• Read this wiki page.
• Make sure the PR has a milestone.
• Assign yourself before merging.
• Either do a regular merge:
  • for PRs containing several commits following conventional-commits,
  • or for PRs containing 1 commit shared with a later PR (to preserve the SHA1)
• Or do a squash-merge:
  • for PRs containing only 1 commit (not shared with a later PR),
  • or for PRs containing several commits that need not be kept in the history;
  • → Update the commit message header with a conventional-commit type,
  • → Add a footer Close #… if a related issue exists.

[erikmd]

I was able to push another small commit (similar to the last-but-one).

Now, the only remaining error raised by make is:

    Error: Multiple rules generated for
    _build/install/default/lib/learn-ocaml/test_lib/test_lib.cmi:
    - src/grader/test_lib/dune:29
    - src/grader/dune:41
    -> required by _build/default/learn-ocaml.install
    -> required by alias install
             ppx src/grader-plugins/mutation_test.pp.mli
             ppx src/grader-plugins/mutation_test.pp.ml
    make: *** [Makefile:13: build] Error