Merge pull request #9996 from Octachron/parallel_manpages

documentation: centralized and parallel builds

.gitattributes

@@ -46,7 +46,8 @@
 *.md                     typo.missing-header
 README*                  typo.missing-header
 *.adoc                   typo.missing-header
-stdlib/*.mld             typo.missing-header
+api_docgen/*.mld                typo.missing-header
+api_docgen/alldoc.tex           typo.missing-header
 tools/mantis2gh_stripped.csv typo.missing-header
 
 *.adoc                   typo.long-line=may

.gitignore

@@ -93,6 +93,13 @@ _build
 /manual/manual/cmds/warnings-help.etex
 /manual/manual/warnings-help.etex
 
+/api_docgen/man
+/api_docgen/html
+/api_docgen/build
+/api_docgen/html
+/api_docgen/latex
+/api_docgen/Compiler_libs.mld
+
 /ocamldoc/ocamldoc
 /ocamldoc/ocamldoc.opt
 /ocamldoc/odoc
@@ -105,10 +112,6 @@ _build
 /ocamldoc/odoc_text_lexer.ml
 /ocamldoc/odoc_text_parser.ml
 /ocamldoc/odoc_text_parser.mli
-/ocamldoc/stdlib_man
-/ocamldoc/stdlib_html
-/ocamldoc/stdlib_latex
-/ocamldoc/stdlib_texi
 /ocamldoc/*.output
 /ocamldoc/test_stdlib
 /ocamldoc/test_latex

HACKING.adoc

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

Makefile

@@ -415,6 +415,9 @@ endif
 	done
 ifneq "$(WITH_OCAMLDOC)" ""
 	$(MAKE) -C ocamldoc install
+endif
+ifeq "$(WITH_OCAMLDOC)-$(STDLIB_MANPAGES)" "ocamldoc-true"
+	$(MAKE) -C api_docgen install
 endif
 	if test -n "$(WITH_DEBUGGER)"; then \
 	  $(MAKE) -C debugger install; \
@@ -879,16 +882,19 @@ partialclean::
 
 .PHONY: html_doc
 html_doc: ocamldoc
-	$(MAKE) -C ocamldoc $@
-	@echo "documentation is in ./ocamldoc/stdlib_html/"
+	$(MAKE) -C api_docgen html
+	@echo "documentation is in ./api_docgen/html/"
 
 .PHONY: manpages
 manpages:
-	$(MAKE) -C ocamldoc $@
+	$(MAKE) -C api_docgen man
 
 partialclean::
 	$(MAKE) -C ocamldoc clean
 
+partialclean::
+	$(MAKE) -C api_docgen clean
+
 # The extra libraries
 
 .PHONY: otherlibraries

api_docgen/Compiler_libs.pre.mld

@@ -0,0 +1,6 @@
+{1 Warning}
+  This library is part of the internal OCaml compiler API, and is
+not the language standard library.
+  There are no compatibility guarantees between releases, so code written
+against these modules must be willing to depend on specific OCaml compiler
+versions.

api_docgen/Makefile

@@ -0,0 +1,161 @@
+#**************************************************************************
+#*                                                                        *
+#*                                 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 = ..
+
+include $(ROOTDIR)/stdlib/StdlibModules
+include $(ROOTDIR)/Makefile.common
+include $(ROOTDIR)/Makefile.best_binaries
+include $(ROOTDIR)/ocamldoc/Makefile.best_ocamldoc
+include 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\
+)
+
+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:
+
+.PHONY: setup
+setup:
+	$(MKDIR) build build/libref build/compilerlibref
+	$(MKDIR) html html/libref html/compilerlibref
+	$(MKDIR) man
+	$(MKDIR) latex
+	$(MKDIR) texi
+
+pdf: latex/alldoc.pdf | setup
+latex: | setup
+man: | setup
+html: | setup
+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
+
+LD_PATH := "$(SRC)/otherlibs/unix/:$(SRC)/otherlibs/str/"
+SET_LD_PATH = CAML_LD_LIBRARY_PATH=$(LD_PATH)
+
+
+$(libref:%=build/libref/%.odoc):build/libref/%.odoc:%.mli
+	$(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
+	$(OCAMLDOC_RUN) -nostdlib -hide Stdlib -lib Stdlib \
+	$(DOC_ALL_INCLUDES) $< -dump  $@
+
+$(compilerlibref_TEXT:%=build/compilerlibref/%.odoc):\
+build/compilerlibref/%.odoc:%.mld
+	$(OCAMLDOC_RUN) $(DOC_ALL_INCLUDES) -text $< -dump  $@
+
+$(libref_TEXT:%=build/libref/%.odoc):build/libref/%.odoc:%.mld
+	$(OCAMLDOC_RUN) $(DOC_STDLIB_INCLUDES) -text $< -dump  $@
+
+ALL_COMPILED_DOC=$(ALL_DOC:%=build/%.odoc)
+man/Stdlib.3o: $(ALL_COMPILED_DOC)
+	$(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)
+	$(MKDIR) -p html/libref
+	$(OCAMLDOC_RUN) -html -d html/libref \
+	-charset="utf8" \
+	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
+	$(addprefix -load , $(ALL_LIBREF:%=build/%.odoc))
+
+html/compilerlibref/Compiler_libs.html: $(ALL_COMPILERLIBREF:%=build/%.odoc)
+	$(MKDIR) -p html/compilerlibref
+	$(OCAMLDOC_RUN) -html -d html/compilerlibref \
+	-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)
+	$(MKDIR) texi
+	$(OCAMLDOC_RUN) -texi -o $@ \
+	-nostdlib -hide Stdlib -lib Stdlib -t "OCaml library" \
+	$(addprefix -load , $(ALL_COMPILED_DOC))
+
+latex/Stdlib.tex: $(ALL_COMPILED_DOC)
+	$(MKDIR) 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
+	cd latex && TEXINPUTS=$${TEXINPUTS}:$(ROOTDIR)/ocamldoc pdflatex alldoc
+	cd latex && TEXINPUTS=$${TEXINPUTS}:$(ROOTDIR)/ocamldoc pdflatex alldoc
+latex/alldoc.tex:alldoc.tex
+	cp $< $@
+
+stdlib_INPUT=$(foreach module,\
+$(filter-out stdlib.mli camlinternal%,$(stdlib_UNPREFIXED)),\
+\\input{$(call capitalize,$(module)).tex}\
+)
+latex/stdlib_input.tex:
+	echo $(stdlib_INPUT)> $@
+
+compilerlibs_INPUT=$(foreach module,\
+$(filter-out camlinternal%,$(compilerlibref)),\
+\\input{$(call capitalize,$(module)).tex})
+latex/compilerlibs_input.tex:
+	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
+
+clean:
+	rm -rf build man html latex texi Compiler_libs.mld

api_docgen/Makefile.docfiles

@@ -0,0 +1,64 @@
+#**************************************************************************
+#*                                                                        *
+#*                                 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.          *
+#*                                                                        *
+#**************************************************************************
+
+define capitalize_one
+$(shell echo $(1) | cut -c1 | tr '[:lower:]' '[:upper:]')$\
+$(shell echo $(1) | cut -c2-)
+endef
+
+define capitalize
+$(foreach m,$(1),$(call capitalize_one,$m))
+endef
+
+
+str_MLIS := str.mli
+unix_MLIS := unix.mli unixLabels.mli
+dynlink_MLIS := dynlink.mli
+thread_MLIS := \
+	thread.mli condition.mli mutex.mli event.mli \
+	threadUnix.mli semaphore.mli
+
+STDLIB=$(filter-out stdlib__pervasives, $(STDLIB_MODULES))
+
+stdlib_UNPREFIXED=$(STDLIB:stdlib__%=%)
+libref= \
+	$(stdlib_UNPREFIXED) \
+	$(str_MLIS:%.mli=%) \
+	$(unix_MLIS:%.mli=%) \
+	$(dynlink_MLIS:%.mli=%) \
+	$(thread_MLIS:%.mli=%)
+libref_EXTRA=stdlib__pervasives
+libref_TEXT=Ocaml_operators
+libref_C=$(call capitalize,$(libref) $(libref_EXTRA))
+
+PARSING_MLIS := $(filter-out camlinternal%, \
+	$(notdir $(wildcard $(ROOTDIR)/parsing/*.mli))\
+)
+UTILS_MLIS := $(notdir $(wildcard $(ROOTDIR)/utils/*.mli))
+DRIVER_MLIS := pparse.mli
+
+compilerlibref_MLIS=\
+  $(PARSING_MLIS) \
+  $(UTILS_MLIS) \
+  $(DRIVER_MLIS)
+compilerlibref=$(compilerlibref_MLIS:%.mli=%)
+compilerlibref_TEXT=Compiler_libs
+compilerlibref_C=$(call capitalize,$(compilerlibref))
+
+ALL_LIBREF= $(libref_TEXT:%=libref/%) $(libref:%=libref/%)
+ALL_COMPILERLIBREF= \
+  $(compilerlibref_TEXT:%=compilerlibref/%) \
+  $(compilerlibref:%=compilerlibref/%)
+ALL_DOC= $(ALL_LIBREF) $(ALL_COMPILERLIBREF)

stdlib/ocaml_operators.mld → api_docgen/Ocaml_operators.mld

@@ -14,7 +14,7 @@ are also listed as references.
 Operator class                                       & Associativity \\
 \hline
 $!\ldots$ $\tilde{}\ldots$                                    &  --   \\
-$.\cdots()$ $.\cdots[]$ $.\cdots\\{\\}$                       &  --   \\
+$.\cdots()$ $.\cdots[]$ $.\cdots$\textbraceleft\textbraceright&  --   \\
 \#\ldots                                                      & left  \\
 function application                                          & left  \\
 - -.                                                          &  --   \\

api_docgen/alldoc.tex

@@ -0,0 +1,34 @@
+\documentclass{book}
+
+\usepackage[colorlinks=true]{hyperref}
+\usepackage{color}
+\usepackage{lmodern}
+\usepackage[T1]{fontenc}
+\usepackage[strings]{underscore}
+\usepackage{textcomp}
+\usepackage{ocamldoc}
+
+\newcommand{\docitem}[2]{\input{#2}}
+\begin{document}
+\chapter{Stdlib}
+\docitem{libref}{Stdlib.tex}
+\input{stdlib_input}
+\docitem{libref}{Ocaml_operators.tex}
+\chapter{Dynlink}
+\docitem{libref}{Dynlink.tex}
+\chapter{Str}
+\docitem{libref}{Str.tex}
+\chapter{Thread}
+\docitem{libref}{Condition.tex}
+\docitem{libref}{Event.tex}
+\docitem{libref}{Mutex.tex}
+\docitem{libref}{Thread.tex}
+\docitem{libref}{ThreadUnix.tex}
+\docitem{libref}{Semaphore.tex}
+\chapter{Unix}
+\docitem{libref}{UnixLabels.tex}
+\docitem{libref}{Unix.tex}
+\chapter{Compilerlibs}
+\docitem{compilerlibref}{Compiler_libs.tex}
+\input{compilerlibs_input.tex}
+\end{document}