documentation: centralized and parallel builds

[Octachron]

This PR proposes to centralize the generation of the documentation for the standard library and the compiler library in one place.

Currently, this build process is scattered between ocamldoc/ and manual/, with slight differences between the two.

This PR moves all the documentation generation logic to a new doc/ directory with the aim to make it easier to tweak the documentation build process (see the next PR).

The new Makefile also handles parallel build for the manpages, accelerating the build process, and making it somewhat incremental.

[gasche]

The idea sounds fine but I don't like doc/. This is the place where, as a newcomer browsing the code repository, I will go to expect to find documentation (maybe on the compiler itself, maybe on the development process). Your directory:

• is not the right place to look for (in the sources) to find documentation
• is not about general documentation of the compiler, but just of the standard library

I would propose either stdlib/docgen or manual/stdlib as better paths for the new "central" place.

[Octachron]

The generated documentation also covers part of the compiler library. I think docgen could work, or maybe api_doc?

[gasche]

We discussed this Very Important Naming Question and agreed on api_docgen at the root directory.

[gasche]

Looks generally good except for a few questions left. I am "approving" in advance of @Octachron handling them in a best-effort way.

[gasche]

Does this magic sed stuff sed "s/\<./\U&/g" work on exotic systems with old Sed versions? (@Octachron and myself wondered if we should use a small OCaml script instead, but properly dealing with spaces-in-directories might be trickier.)

[xavierleroy]

Does this magic sed stuff sed "s/\<./\U&/g" work on exotic systems with old Sed versions?

The \U replacement (meaning "convert to uppercase", I guess) is no documented in POSIX sed, so the answer is no, it's not going to work everywhere. And it's the first time I see this replacement!

[xavierleroy]

Here is a classic sed implementation that I've been using since the 90's:

sed -e 'h
s/\(.\).*/\1/
y/abcdefghijklmnopqrstuvwxyz/ABCDEFGHIJKLMNOPQRSTUVWXYZ/
G
s/\n.//'

[gasche]

Yes, the good sed scripts are from the 90s :-)

[xavierleroy]

Here is a sed-free solution. Recommended!

define capitalize
$(shell echo $(1) | cut -c1 | tr '[:lower:]' '[:upper:]')$(shell echo $(1) | cut -c2-)
endef

[Octachron]

Then let's go for the recommended solution and a bit of glue rather than a GNUism.

[gasche]

There seems to be a relevant failure that the full-flambda CI complains about:

+ make -j -C ocamldoc html_doc pdf_doc texi_doc
make: Entering directory '/home/runner/work/ocaml/ocaml/ocamldoc'
make: *** No rule to make target 'html_doc'.  Stop.
make: Leaving directory '/home/runner/work/ocaml/ocaml/ocamldoc'
Error: Process completed with exit code 2.

[Octachron]

Indeed, I forgot to update the patch to the CI after @dra27 changes.