Try to fix the #526 documentation issue

[erikmd]

• Kind: bugfix for documentation

Try to Fix #526 (https://github.com/ocaml-sf/learn-ocaml/issues/526#issuecomment-2614563600)

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: https://github.com/ocaml-sf/learn-ocaml/blob/c8174f8edbf80629af14f2fa9ae1fd536b8c26f7/src/grader-plugins/dune#L9 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.
• [x] ~~Issue 3:~~ the doc. home page does not mention Mutation_test → this is now fixed thanks to https://github.com/ocaml-sf/learn-ocaml/pull/607/commits/bd79ffe3f0047c6b987cfbd1e78623fdcbe0c9fe updating the index.mld file.

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

https://github.com/ocaml-sf/learn-ocaml/blob/c8174f8edbf80629af14f2fa9ae1fd536b8c26f7/src/grader/test_lib/dune#L21-L29

and that it might suffice to tweak these stanzas:

https://github.com/ocaml-sf/learn-ocaml/blob/c8174f8edbf80629af14f2fa9ae1fd536b8c26f7/src/grader/dune#L11-L15

https://github.com/ocaml-sf/learn-ocaml/blob/c8174f8edbf80629af14f2fa9ae1fd536b8c26f7/src/grader/dune#L60-L64

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

Checklist

• [x] Read the CONTRIBUTING.md guide and:
  • [x] Use Atomic Commits so each commit gathers a single logical change
  • [x] Use Conventional Commits regarding commit messages (needed by our release toolchain)
• [ ] Add/update tests
• [x] 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