documentation: configuration switch for an odoc documentation mode

.gitignore

@@ -93,12 +93,9 @@ _build
 /manual/src/cmds/warnings-help.etex
 /manual/src/warnings-help.etex
 
-/api_docgen/man
-/api_docgen/html
 /api_docgen/build
-/api_docgen/latex
-/api_docgen/texi
-/api_docgen/Compiler_libs.mld
+/api_docgen/odoc/build
+/api_docgen/ocamldoc/build
 
 /ocamldoc/ocamldoc
 /ocamldoc/ocamldoc.opt

Changes

@@ -170,6 +170,11 @@ Working version
   (François Bobot, Nicolás Ojeda Bär, review by Daniel Bünzli and Damien
   Doligez)
 
+- #9987, #9988, #9996, #9997: add an odoc mode for the documentation
+  of the standard library and compiler library
+  (Florian Angeletti, review by David Allsopp, Sébastien Hinderer,
+   and Gabriel Scherer)
+
 ### Compiler user-interface and warnings:
 
 - #9407: added warning for missing mli interface file

HACKING.adoc

@@ -144,7 +144,7 @@ result by running
 make html_doc
 ----
 
-and then opening link:./api_docgen/html/libref/index.html[] in a web browser.
+and then opening link:./api_docgen/build/html/libref/index.html[] in a web browser.
 
 === Tools
 

Makefile.build_config.in

@@ -34,3 +34,7 @@ OC_DLL_LDFLAGS=@oc_dll_ldflags@
 
 # The rlwrap command (for the *runtop targets)
 RLWRAP=@rlwrap@
+
+# Which document generator: odoc or ocamldoc?
+DOCUMENTATION_TOOL=@documentation_tool@
+DOCUMENTATION_TOOL_CMD=@documentation_tool_cmd@

api_docgen/Makefile

@@ -13,142 +13,19 @@
 #*                                                                        *
 #**************************************************************************
 ROOTDIR = ..
+-include $(ROOTDIR)/Makefile.build_config
 
-include $(ROOTDIR)/stdlib/StdlibModules
-include $(ROOTDIR)/Makefile.common
-include $(ROOTDIR)/Makefile.best_binaries
-include $(ROOTDIR)/ocamldoc/Makefile.best_ocamldoc
-include Makefile.docfiles
+ifeq ($(DOCUMENTATION_TOOL),odoc)
+  include odoc/Makefile
+else
+  include ocamldoc/Makefile
+endif
 
-DOC_COMPILERLIBS_DIRS= $(addprefix $(ROOTDIR)/, \
-parsing utils typing bytecomp driver file_formats lambda\
-)
+odoc-%:
+	$(MAKE) -C odoc $* ROOTDIR=../..
 
-DOC_STDLIB_DIRS = $(addprefix $(ROOTDIR)/, stdlib \
-	otherlibs/str \
-	otherlibs/$(UNIXLIB) otherlibs/dynlink \
-	otherlibs/systhreads\
-)
-
-DOC_STDLIB_INCLUDES=$(addprefix -I , $(DOC_STDLIB_DIRS))
-
-DOC_ALL_INCLUDES = \
-	$(DOC_STDLIB_INCLUDES) \
-	$(addprefix -I ,$(DOC_COMPILERLIBS_DIRS))
-
-ALL_MAN= $(ALL_DOC:%=man/%.3o)
-ALL_LATEX= $(ALL_DOC:%=latex/%.tex)
-
-all: html pdf man
-.PHONY:all
-.SUFFIXES:
-
-DIRS = build/libref build/compilerlibref man/ latex/ texi/ \
-	html/ html/libref html/compilerlibref
-
-$(DIRS):
-	$(MKDIR) $@
-
-pdf: latex/alldoc.pdf
-latex/alldoc.pdf: latex/stdlib_input.tex latex/compilerlibs_input.tex
-
-Compiler_libs.mld: Compiler_libs.pre.mld
-	cp $< $@ && echo "{!modules:$(compilerlibref_C)}" >> $@
-
-vpath %.mli $(ROOTDIR)/stdlib $(DOC_COMPILERLIBS_DIRS)  $(DOC_STDLIB_DIRS)
-
-man: man/Stdlib.3o
-html: html/libref/Stdlib.html html/compilerlibref/Compiler_libs.html
-latex: latex/Stdlib.tex
-texi: texi/stdlib.texi
-
-LD_PATH := "$(ROOTDIR)/otherlibs/unix/:$(ROOTDIR)/otherlibs/str/"
-SET_LD_PATH = CAML_LD_LIBRARY_PATH=$(LD_PATH)
-
-
-$(libref:%=build/libref/%.odoc): build/libref/%.odoc: %.mli | build/libref
-	$(OCAMLDOC_RUN) -nostdlib -hide Stdlib -lib Stdlib \
-	-pp \
-"$(AWK) -v ocamldoc=true -f $(ROOTDIR)/stdlib/expand_module_aliases.awk" \
-	$(DOC_STDLIB_INCLUDES) $< -dump  $@
-
-$(compilerlibref:%=build/compilerlibref/%.odoc):\
-build/compilerlibref/%.odoc: %.mli | build/compilerlibref
-	$(OCAMLDOC_RUN) -nostdlib -hide Stdlib -lib Stdlib \
-	$(DOC_ALL_INCLUDES) $< -dump  $@
-
-$(compilerlibref_TEXT:%=build/compilerlibref/%.odoc):\
-build/compilerlibref/%.odoc: %.mld | build/compilerlibref
-	$(OCAMLDOC_RUN) $(DOC_ALL_INCLUDES) -text $< -dump  $@
-
-$(libref_TEXT:%=build/libref/%.odoc): build/libref/%.odoc: %.mld | build/libref
-	$(OCAMLDOC_RUN) $(DOC_STDLIB_INCLUDES) -text $< -dump  $@
-
-ALL_COMPILED_DOC=$(ALL_DOC:%=build/%.odoc)
-man/Stdlib.3o: $(ALL_COMPILED_DOC) | man/
-	$(MKDIR) man
-	$(OCAMLDOC_RUN) -man -d man -man-mini \
-	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
-	$(addprefix -load , $(ALL_COMPILED_DOC))
-
-html/libref/Stdlib.html: $(ALL_LIBREF:%=build/%.odoc) | html/libref
-	$(OCAMLDOC_RUN) -html -d html/libref \
-	-charset="utf8" \
-	-nonavbar -nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
-	$(addprefix -load , $(ALL_LIBREF:%=build/%.odoc))
-
-html/compilerlibref/Compiler_libs.html: $(ALL_COMPILERLIBREF:%=build/%.odoc) \
-| html/compilerlibref
-	$(OCAMLDOC_RUN) -html -d html/compilerlibref \
-	-nonavbar -nostdlib -hide Stdlib -t "OCaml compiler library" \
-	-charset="utf8" \
-	-intro Compiler_libs.mld \
-	$(addprefix -load , $(ALL_COMPILERLIBREF:%=build/%.odoc))
-
-texi/stdlib.texi: $(ALL_COMPILED_DOC) | texi/
-	$(OCAMLDOC_RUN) -texi -o $@ \
-	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
-	$(addprefix -load , $(ALL_COMPILED_DOC))
-
-latex/Stdlib.tex: $(ALL_COMPILED_DOC) | latex/
-	$(OCAMLDOC_RUN) -latex -o latex/all.tex \
-	-hide Stdlib -lib Stdlib $(DOC_ALL_INCLUDES) \
-	-sepfiles \
-	-latextitle "1,subsection*" \
-	-latextitle "2,subsubsection*" \
-	-latex-type-prefix "TYP" \
-	-latex-module-prefix "" \
-	-latex-module-type-prefix "" \
-	-latex-value-prefix "" \
-	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
-	$(addprefix -load , $(ALL_COMPILED_DOC))
-
-latex/alldoc.pdf: latex/Stdlib.tex latex/alldoc.tex | latex/
-	cd latex && TEXINPUTS=$${TEXINPUTS}:$(ROOTDIR)/ocamldoc pdflatex alldoc
-	cd latex && TEXINPUTS=$${TEXINPUTS}:$(ROOTDIR)/ocamldoc pdflatex alldoc
-latex/alldoc.tex:alldoc.tex | latex/
-	cp $< $@
-
-stdlib_INPUT=$(foreach module,\
-$(filter-out stdlib.mli camlinternal%,$(stdlib_UNPREFIXED)),\
-\\input{$(call capitalize,$(module)).tex}\
-)
-latex/stdlib_input.tex: | latex/
-	echo $(stdlib_INPUT) > $@
-
-compilerlibs_INPUT=$(foreach module,\
-$(filter-out camlinternal%,$(compilerlibref)),\
-\\input{$(call capitalize,$(module)).tex})
-latex/compilerlibs_input.tex: | latex/
-	echo $(compilerlibs_INPUT) > $@
-
-INSTALL_MANODIR=$(INSTALL_MANDIR)/man3
-.PHONY:install
-install:
-	$(MKDIR) "$(INSTALL_MANODIR)"
-	if test -d man; then \
-	  $(INSTALL_DATA) man/* "$(INSTALL_MANODIR)"; \
-	else : ; fi
+ocamldoc-%:
+	$(MAKE) -C ocamldoc $* ROOTDIR=../..
 
 clean:
-	rm -rf build/ man/ html/ latex/ texi/ Compiler_libs.mld
+	rm -rf build odoc/build ocamldoc/build

api_docgen/Makefile.common

@@ -0,0 +1,56 @@
+#**************************************************************************
+#*                                                                        *
+#*                                 OCaml                                  *
+#*                                                                        *
+#*             Florian Angeletti, projet Cambium, Inria Paris             *
+#*                                                                        *
+#*   Copyright 2020 Institut National de Recherche en Informatique et     *
+#*     en Automatique.                                                    *
+#*                                                                        *
+#*   All rights reserved.  This file is distributed under the terms of    *
+#*   the GNU Lesser General Public License version 2.1, with the          *
+#*   special exception on linking described in the file LICENSE.          *
+#*                                                                        *
+#**************************************************************************
+ROOTDIR = ..
+DOCGEN= $(ROOTDIR)/api_docgen
+
+-include $(ROOTDIR)/stdlib/StdlibModules
+include $(ROOTDIR)/Makefile.common
+include $(ROOTDIR)/Makefile.best_binaries
+include $(DOCGEN)/Makefile.docfiles
+
+DOC_COMPILERLIBS_DIRS= $(addprefix $(ROOTDIR)/,\
+  parsing utils typing bytecomp driver file_formats lambda)
+
+DOC_STDLIB_DIRS = $(addprefix $(ROOTDIR)/, stdlib \
+  otherlibs/str otherlibs/$(UNIXLIB) otherlibs/dynlink \
+  otherlibs/systhreads)
+
+.PHONY: all
+all: html pdf man
+
+DIRS = $(addprefix build/,libref compilerlibref man latex texi \
+  html html/libref html/compilerlibref)
+
+$(DIRS):
+	$(MKDIR) $@
+
+pdf: build/latex/alldoc.pdf
+latex:
+man:
+html:
+build/latex/alldoc.pdf: build/latex/stdlib_input.tex \
+  build/latex/compilerlibs_input.tex | build/latex/ifocamldoc.tex
+
+$(DOCGEN)/build/Compiler_libs.mld: $(DOCGEN)/Compiler_libs.pre.mld
+	cp $< $@ && echo "{!modules:$(compilerlibref_C)}" >> $@
+
+build/latex/ifocamldoc.tex: $(ROOTDIR)/Makefile.config | build/latex
+
+build/latex/alldoc.tex:$(DOCGEN)/alldoc.tex | build/latex
+	cp $< $@
+
+$(compilerlibref_TEXT:%=build/%.mld) $(libref_TEXT:%=build/%.mld): \
+build/%.mld:$(DOCGEN)/%.mld
+	cp $< $@

api_docgen/Makefile.docfiles

@@ -26,6 +26,10 @@ define capitalize
 $(foreach m,$(1),$(call capitalize_one,$m))
 endef
 
+define sort
+$(shell $(BEST_OCAMLDEP) -sort $(1))
+endef
+
 
 str_MLIS := str.mli
 unix_MLIS := unix.mli unixLabels.mli
@@ -34,8 +38,11 @@ thread_MLIS := \
 	thread.mli condition.mli mutex.mli event.mli \
 	threadUnix.mli semaphore.mli
 
-libref= \
-	$(filter-out pervasives,$(STDLIB_MODULE_BASENAMES)) \
+STDLIB=$(filter-out stdlib__Pervasives, $(STDLIB_MODULES))
+
+stdlib_UNPREFIXED=$(filter-out pervasives, $(STDLIB_MODULE_BASENAMES))
+
+otherlibref= \
 	$(str_MLIS:%.mli=%) \
 	$(unix_MLIS:%.mli=%) \
 	$(dynlink_MLIS:%.mli=%) \
@@ -44,13 +51,13 @@ libref_EXTRA=stdlib__pervasives
 libref_TEXT=Ocaml_operators Format_tutorial
 libref_C=$(call capitalize,$(libref) $(libref_EXTRA))
 
-PARSING_MLIS := $(filter-out camlinternal%, \
+PARSING_MLIS := $(call sort, \
 	$(notdir $(wildcard $(ROOTDIR)/parsing/*.mli))\
 )
-UTILS_MLIS := $(notdir $(wildcard $(ROOTDIR)/utils/*.mli))
+UTILS_MLIS := $(call sort,$(notdir $(wildcard $(ROOTDIR)/utils/*.mli)))
 DRIVER_MLIS := pparse.mli
 
-compilerlibref_MLIS=\
+compilerlibref_MLIS= \
   $(PARSING_MLIS) \
   $(UTILS_MLIS) \
   $(DRIVER_MLIS)

api_docgen/alldoc.tex

@@ -1,14 +1,73 @@
 \documentclass{book}
 
-\usepackage[colorlinks=true]{hyperref}
+\usepackage[colorlinks=true,breaklinks=true]{hyperref}
 \usepackage{color}
 \usepackage{lmodern}
 \usepackage[T1]{fontenc}
-\usepackage[strings]{underscore}
-\usepackage{textcomp}
+\usepackage[strings,nohyphen]{underscore}
+\input{ifocamldoc}
+\ifocamldoc
 \usepackage{ocamldoc}
+\usepackage{textcomp}
+\else
+\usepackage{changepage}
+\usepackage{longtable}
+\usepackage{listings}
+\newcommand{\ocamlcodefragment}[1]{{\ttfamily\setlength{\parindent}{0cm}%
+\raggedright#1}}
+\newcommand{\ocamlinlinecode}[1]{{\ttfamily#1}}
+\newcommand{\bold}[1]{{\bfseries#1}}
+\newenvironment{ocamlexception}{\bfseries}{}
+\newenvironment{ocamlextension}{\bfseries}{}
+\newenvironment{ocamlarrow}{}
+
+\newcommand{\ocamltag}[2]{\begin{ocaml#1}#2\end{ocaml#1}}
+\newenvironment{ocamlkeyword}{\bfseries}{}
+\newenvironment{ocamlconstructor}{\bfseries}{}
+\newenvironment{ocamltype-var}{\itshape\ttfamily}{}
+
+\newcommand{\ocamlhighlight}{\bfseries\uline}
+\newcommand{\ocamlerror}{\bfseries}
+\newcommand{\ocamlwarning}{\bfseries}
 
+\definecolor{lightgray}{gray}{0.97}
+\definecolor{gray}{gray}{0.5}
+\newcommand{\ocamlcomment}{\color{gray}\normalfont\small}
+\newcommand{\ocamlstring}{\color{gray}\bfseries}
+\newenvironment{ocamlindent}{\begin{adjustwidth}{2em}{0pt}}{\end{adjustwidth}}
+\newenvironment{ocamltabular}[2][l]{\begin{tabular}{#2}}%
+{\end{tabular}}
+
+\lstnewenvironment{ocamlcodeblock}{
+  \lstset{
+    backgroundcolor = \color{lightgray},
+    basicstyle=\ttfamily,
+    showstringspaces=false,
+    language=caml,
+    escapeinside={$}{$},
+    columns=fullflexible,
+    stringstyle=\ocamlstring,
+    commentstyle=\ocamlcomment,
+    keepspaces=true,
+    keywordstyle=\ocamlkeyword,
+    moredelim=[is][\ocamlhighlight]{<<}{>>},
+    moredelim=[s][\ocamlstring]{\{|}{|\}},
+    moredelim=[s][\ocamlstring]{\{delimiter|}{|delimiter\}},
+    keywords={[2]{val,initializer,nonrec}}, keywordstyle={[2]\ocamlkeyword},
+    belowskip=0\baselineskip,
+    upquote=true,
+    literate={'"'}{\textquotesingle "\textquotesingle}3
+    {'\\"'}{\textquotesingle \textbackslash"\textquotesingle}4,
+  }
+}{}
+\fi
+
+\ifocamldoc
 \newcommand{\docitem}[2]{\input{#2}}
+\else
+\newcommand{\docitem}[2]{\input{#1/#2}}
+\fi
+
 \begin{document}
 \chapter{Stdlib}
 \docitem{libref}{Stdlib.tex}