List of modules in the stdlib should be sorted

[talex5]

At the moment, https://v2.ocaml.org/releases/5.0/api/index.html seems to be in a random order. It starts:

• Ocaml_operators
• Format_tutorial
• CamlinternalFormatBasics
• Stdlib
• Either
• Sys
• Obj
• Atomic
• ...

(@gasche reminded me of the importance of sorting in documentation in https://discuss.ocaml.org/t/dune-wish-list-for-2023/11083/26)

[gasche]

This list was sorted in the past, it looks like this is a regression that occurred for 4.13:

• https://v2.ocaml.org/releases/4.12/api/index.html : sorted
• https://v2.ocaml.org/releases/4.13/api/index.html: not sorted

[gasche]

@Octachron I can observe this issue in ocaml/ocaml upstream by:

make -C api_docgen clean
make html_doc -j
less ./api_docgen/ocamldoc/build/html/libref/index.html 

The following patch appears to fix the issue (at least in part):

diff --git a/api_docgen/Makefile.docfiles b/api_docgen/Makefile.docfiles
index 2d77fe6984..487bf304c7 100644
--- a/api_docgen/Makefile.docfiles
+++ b/api_docgen/Makefile.docfiles
@@ -76,8 +76,13 @@ compilerlibref=$(compilerlibref_MLIS:%.mli=%)
 compilerlibref_TEXT=Compiler_libs
 compilerlibref_C=$(call capitalize,$(compilerlibref))
 
-ALL_LIBREF= $(libref_TEXT:%=libref/%) $(libref:%=libref/%)
+ALL_LIBREF= $(call sort,$(libref_TEXT:%=libref/%) $(libref:%=libref/%))
 ALL_COMPILERLIBREF= \
   $(compilerlibref_TEXT:%=compilerlibref/%) \
   $(compilerlibref:%=compilerlibref/%)
 ALL_DOC= $(ALL_LIBREF) $(ALL_COMPILERLIBREF)

(I don't understand why this patch works, because sort is defined as ocamldep -sort which itself is documented as sorting by dependencies, while in practice it appears to sort alphabetically.)

(The patch keeps capitalized modules, namely Format_tutorial and OCaml_operators, at the front -- other modules come from uncapitalized module names so they get sorted after. I think this is an okay result, in any case we would rather have users read https://v2.ocaml.org/releases/5.0/manual/stdlib.html than the auto-generated https://v2.ocaml.org/releases/5.0/api/index.html.)

If you ( @Octachron ) can confirm that this is an upstream issue, we can move the discussion there.

[Octachron]

This is almost certainly an issue on the compiler side (since the documentation at v2.ocaml.org is a direct copy of the documentation generated by the compiler).

[gasche]

The documentation generation issue was fixed upstream by @Octachron ( ocaml/ocaml#11860 ). I believe that he is planning to update the ocaml.org manual pages for 4.13, 4.14 and 5.0 -- once this is done we can close the present issue.

[tmattio]

Fixed by @Octachron in ocaml/v2.ocaml.org#1631