install: adapt doc build process to sphinx

Change makefile to build doc with sphinx rather pod. Docs are now pregenerated in dist-tarball, to avoid requiring documentation build tool when installing from these dist-tarball. Adapt travis conf & RPM spec file to the new documentation build process.
cea-hpc · Oct 7, 2017 · eb5849e · eb5849e
1 parent 4204472
commit eb5849e
Show file tree

Hide file tree

Showing 11 changed files with 102 additions and 148 deletions.
diff --git a/.gitignore b/.gitignore
@@ -17,10 +17,8 @@
 /contrib/scripts/add.modules
 /contrib/modulefiles/modules
 /compat
-/doc/diff_v3_v4.txt
-/doc/html/*.html
-/doc/man
-/doc/source/module.pod
+/doc/build
+/doc/source/version.py
 /www/tcl
 /www/docs
 /modules-*.tar

diff --git a/.travis.yml b/.travis.yml
@@ -20,6 +20,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -33,6 +34,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -51,6 +53,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -65,6 +68,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -84,6 +88,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -103,6 +108,7 @@ matrix:
             - sourceline: 'ppa:fish-shell/release-2'
           packages:
             - dejagnu
+            - python-sphinx
             - bash
             - tcsh
             - ksh
@@ -181,11 +187,12 @@ before_install: |
     docker run --name $CONTAINER --detach --rm -i -t -w /modules $DOCKER_IMAGE /bin/bash
     case "${OS_NAME}" in
       centos)
-        docker exec $CONTAINER yum install -y tcsh zsh ksh tcl make wget perl perl-podlators git dejagnu man-db $EXTRA_PKGS &&
+        if [ $OS_VERSION -eq 6 ]; then SPHINX_PKG='python-sphinx10'; else SPHINX_PKG='python-sphinx'; fi
+        docker exec $CONTAINER yum install -y tcsh zsh ksh tcl make wget perl $SPHINX_PKG git dejagnu man-db $EXTRA_PKGS &&
         docker exec $CONTAINER wget -O /etc/yum.repos.d/shells_fish_release_2.repo http://download.opensuse.org/repositories/shells:fish:release:2/CentOS_${OS_VERSION}/shells:fish:release:2.repo &&
         docker exec $CONTAINER yum install -y fish ;;
       opensuse)
-        docker exec $CONTAINER zypper install -y tcsh zsh ksh fish tcl make wget perl git dejagnu man net-tools $EXTRA_PKGS ;;
+        docker exec $CONTAINER zypper install -y tcsh zsh ksh fish tcl make wget perl python-Sphinx git dejagnu man net-tools $EXTRA_PKGS ;;
     esac
     docker cp ./. $CONTAINER:modules
   else

diff --git a/INSTALL.txt b/INSTALL.txt
@@ -22,8 +22,6 @@ the tools to be found on your system:
  * perl
  * grep
  * cut
- * pod2text
- * pod2man
  * runtest
 
 

diff --git a/Makefile b/Makefile
@@ -156,10 +156,14 @@ endif
 	rmdir $(DESTDIR)$(datarootdir)
 	rmdir --ignore-fail-on-non-empty $(DESTDIR)$(prefix)
 
-dist-tar: ChangeLog README MIGRATING version.inc
+# include pre-generated documents not to require documentation build
+# tools when installing from dist tarball
+dist-tar: ChangeLog README MIGRATING version.inc pkgdoc
 	git archive --prefix=$(DIST_PREFIX)/ --worktree-attributes \
 		-o $(DIST_PREFIX).tar HEAD
-	tar -rf $(DIST_PREFIX).tar --transform 's,^,$(DIST_PREFIX)/,' $^
+	tar -rf $(DIST_PREFIX).tar --transform 's,^,$(DIST_PREFIX)/,' \
+		ChangeLog README MIGRATING version.inc doc/build/diff_v3_v4.txt \
+		doc/build/module.1.in doc/build/modulefile.4
 ifeq ($(compatversion) $(wildcard $(COMPAT_DIR)),y $(COMPAT_DIR))
 	make -C $(COMPAT_DIR) distdir
 	mv $(COMPAT_DIR)/modules-* compatdist

diff --git a/Makefile.inc.in b/Makefile.inc.in
@@ -27,4 +27,5 @@ examplemodulefiles := @examplemodulefiles@
 
 # command location
 TCLSH := @TCLSH@
+SPHINXBUILD := @SPHINXBUILD@
 
diff --git a/README.md b/README.md
@@ -89,8 +89,7 @@ regarding changes.
 
 The `doc` directory contains both the paper and man pages describing the
 user's and the module writer's usage. To generate the documentation files,
-like the man pages (you need Perl podlators to build the documentation),
-just type:
+like the man pages (you need Sphinx to build the documentation), just type:
 
     $ ./configure
     $ make -C doc all

diff --git a/configure b/configure
@@ -26,9 +26,9 @@ prog=${progpath##*/}
 targetlist="${progdir}/Makefile.inc ${progdir}/site.exp"
 
 # argument list
-arglist="TCLSH prefix bindir libexecdir initdir datarootdir mandir docdir \
-modulefilesdir setmanpath setbinpath setdotmodulespath docinstall \
-examplemodulefiles compatversion modulepath loadedmodules"
+arglist="TCLSH SPHINXBUILD prefix bindir libexecdir initdir datarootdir \
+mandir docdir modulefilesdir setmanpath setbinpath setdotmodulespath \
+docinstall examplemodulefiles compatversion modulepath loadedmodules"
 compatarglist=
 
 # flags to know if argument has been specified on command-line
@@ -45,6 +45,7 @@ examplemodulefiles=y
 compatversion=y
 loadedmodules=
 TCLSH=tclsh
+SPHINXBUILD=sphinx-build
 # these args are initialized here but as they depend on other argument value
 # they will get their default value later (after command-line parse)
 bindir=
@@ -148,21 +149,29 @@ placed in the following directory structure:
 # check requirement availability
 check_requirement() {
    typeset req=$1
-   typeset optmesg=$2
-   typeset cmdenv=$3
-
-   echo -n "checking for ${req}... "
-   if [ -n "$cmdenv" ]; then
-      cmdsearch="$cmdenv command -v $req"
-   else
-      cmdsearch="command -v $req"
-   fi
-   reqpath=$(eval $cmdsearch)
+   typeset alt=$2
+   typeset optmesg=$3
+   typeset cmdenv=$4
+
+   for cmd in $req $alt; do
+      if [ -n "$cmd" ]; then
+         echo -n "checking for ${cmd}... "
+         if [ -n "$cmdenv" ]; then
+            cmdsearch="$cmdenv command -v $cmd"
+         else
+            cmdsearch="command -v $cmd"
+         fi
+         reqpath=$(eval $cmdsearch)
+         if [ -n "$reqpath" ]; then
+            echo $reqpath
+            break
+         else
+            echo "not found"
+         fi
+      fi
+   done
 
-   if [ -n "$reqpath" ]; then
-      echo $reqpath
-   else
-      echo "not found"
+   if [ -z "$reqpath" ]; then
       if [ -z "$optmesg" ]; then
          echo_error "$req could not be found"
       else
@@ -270,16 +279,19 @@ check_requirement make
 check_requirement perl
 check_requirement grep
 check_requirement cut
-check_requirement pod2text
-check_requirement pod2man
-check_requirement pod2html "Install \`pod2html' if you want to build html \
-documentation"
-check_requirement runtest "Install \`dejagnu' if you want to run the \
+check_requirement runtest '' "Install \`dejagnu' if you want to run the \
 testsuite"
+
+# if we install from git repository, must have sphinx to build doc
+if [ -d '.git' ]; then
+   check_requirement sphinx-build sphinx-1.0-build
+   SPHINXBUILD=$reqpath
+fi
+
 # get tclsh location from standard PATHs or /usr/local/bin
 # or validate location passed as argument
 [ -z "$tclshbin" ] && tclshbin=$TCLSH
-check_requirement $tclshbin '' 'PATH=/usr/bin:/bin:/usr/local/bin'
+check_requirement $tclshbin '' '' 'PATH=/usr/bin:/bin:/usr/local/bin'
 TCLSH=$reqpath
 
 # check feature requirements are met

diff --git a/contrib/rpm/environment-modules.spec b/contrib/rpm/environment-modules.spec
@@ -13,9 +13,6 @@ Source0:        http://downloads.sourceforge.net/modules/modules-%{version}-beta
 BuildRequires:  tcl
 BuildRequires:  dejagnu
 BuildRequires:  perl
-%if 0%{?fedora} || (0%{?rhel} && 0%{?rhel} > 6)
-BuildRequires:  perl-podlators
-%endif
 %if 0%{?rhel} && 0%{?rhel} <= 6
 BuildRequires:  net-tools
 %else

diff --git a/doc/Makefile b/doc/Makefile
@@ -1,10 +1,9 @@
 .PHONY: install uninstall clean
 
-HTML_DIR := html
-MAN_DIR := man
-MAN1_DIR := $(MAN_DIR)/man1
-MAN4_DIR := $(MAN_DIR)/man4
 SOURCE_DIR := source
+BUILD_DIR := build
+
+SPHINXOPTS := -q
 
 # compatibility version-related files
 COMPAT_MAN_DIR := ../compat/doc
@@ -18,22 +17,22 @@ include ../Makefile.inc
 # source version definitions shared across the Makefiles of this project
 include ../version.inc
 
-MAN_VERSION := "modules $(MODULES_RELEASE)$(MODULES_BUILD)"
-MAN_HEADER := "Environment Modules"
-
+man: $(BUILD_DIR)/module.1 $(BUILD_DIR)/modulefile.4
 ifeq ($(compatversion),y)
-man: $(MAN1_DIR)/module.1 $(MAN4_DIR)/modulefile.4 \
-	$(COMPAT_MAN_DIR)/module.1 $(COMPAT_MAN_DIR)/modulefile.4
-else
-man: $(MAN1_DIR)/module.1 $(MAN4_DIR)/modulefile.4
+man: $(COMPAT_MAN_DIR)/module.1 $(COMPAT_MAN_DIR)/modulefile.4
 endif
 
-txt: diff_v3_v4.txt
+txt: $(BUILD_DIR)/diff_v3_v4.txt
 
-html: $(HTML_DIR)/module.html $(HTML_DIR)/modulefile.html \
-	$(HTML_DIR)/diff_v3_v4.html
+html: $(BUILD_DIR)/module.html $(BUILD_DIR)/modulefile.html \
+      $(BUILD_DIR)/diff_v3_v4.html
 
-all: html man txt
+all: man txt
+
+# enable HTML pages build only from git repository
+ifeq ($(wildcard ../.git),../.git)
+all: html
+endif
 
 define translate-in-script
 perl -pe 's|\@prefix\@|$(prefix)|g; \
@@ -45,24 +44,29 @@ endef
 # avoid shared definitions to be rebuilt by make
 ../Makefile.inc ../version.inc: ;
 
-$(SOURCE_DIR)/%.pod: $(SOURCE_DIR)/%.pod.in
-	$(translate-in-script)
+# build doc from source if in git repository
+ifeq ($(wildcard ../.git),../.git)
+$(SOURCE_DIR)/version.py: $(SOURCE_DIR)/version.py.in ../version.inc
+	perl -pe 's|\@MODULES_RELEASE\@|$(MODULES_RELEASE)|g; \
+		s|\@MODULES_BUILD\@|$(MODULES_BUILD)|g; \
+		s|\@MODULES_BUILD_DATE\@|$(MODULES_BUILD_DATE)|g;' $< > $@
 
-$(HTML_DIR)/%.html: $(SOURCE_DIR)/%.pod
-	mkdir -p $(HTML_DIR)
-	pod2html --noindex --css=common.css --infile=$< --outfile=$@
-	rm -f pod2htmd.tmp
+$(BUILD_DIR)/%.html: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
+	$(SPHINXBUILD) $(SPHINXOPTS) -b html "$(SOURCE_DIR)" "$(BUILD_DIR)"
 
-$(MAN1_DIR)/%.1: $(SOURCE_DIR)/%.pod ../version.inc
-	mkdir -p $(MAN1_DIR)
-	pod2man -c $(MAN_HEADER) -r $(MAN_VERSION) -d $(MODULES_BUILD_DATE) -s 1 $< $@
+$(BUILD_DIR)/%.txt: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
+	$(SPHINXBUILD) $(SPHINXOPTS) -b text "$(SOURCE_DIR)" "$(BUILD_DIR)"
 
-$(MAN4_DIR)/%.4: $(SOURCE_DIR)/%.pod ../version.inc
-	mkdir -p $(MAN4_DIR)
-	pod2man -c $(MAN_HEADER) -r $(MAN_VERSION) -d $(MODULES_BUILD_DATE) -s 4 $< $@
+$(BUILD_DIR)/%.4: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
+	$(SPHINXBUILD) $(SPHINXOPTS) -t pathsubs -b man "$(SOURCE_DIR)" "$(BUILD_DIR)"
 
-%.txt: $(SOURCE_DIR)/%.pod
-	pod2text $< >$@
+$(BUILD_DIR)/%.1.in: $(SOURCE_DIR)/%.rst $(SOURCE_DIR)/version.py
+	$(SPHINXBUILD) $(SPHINXOPTS) -t pathsubs -b man "$(SOURCE_DIR)" "$(BUILD_DIR)"
+	mv $(BUILD_DIR)/module.1 $@
+endif
+
+$(BUILD_DIR)/module.1: $(BUILD_DIR)/module.1.in
+	$(translate-in-script)
 
 # compatibility version-related rules
 $(COMPAT_MAN_DIR)/module.1 $(COMPAT_MAN_DIR)/modulefile.4:
@@ -72,11 +76,11 @@ install: man txt
 	mkdir -p $(DESTDIR)$(mandir)/man1 $(DESTDIR)$(mandir)/man4
 ifeq ($(docinstall),y)
 	mkdir -p $(DESTDIR)$(docdir)
-	cp diff_v3_v4.txt $(DESTDIR)$(docdir)/
+	cp $(BUILD_DIR)/diff_v3_v4.txt $(DESTDIR)$(docdir)/
 	cp example.txt $(DESTDIR)$(docdir)/
 endif
-	cp $(MAN1_DIR)/module.1 $(DESTDIR)$(mandir)/man1/
-	cp $(MAN4_DIR)/modulefile.4 $(DESTDIR)$(mandir)/man4/
+	cp $(BUILD_DIR)/module.1 $(DESTDIR)$(mandir)/man1/
+	cp $(BUILD_DIR)/modulefile.4 $(DESTDIR)$(mandir)/man4/
 ifeq ($(compatversion),y)
 	cp $(COMPAT_MAN_DIR)/module.1 $(DESTDIR)$(mandir)/man1/module-compat.1
 	cp $(COMPAT_MAN_DIR)/modulefile.4 $(DESTDIR)$(mandir)/man4/modulefile-compat.4
@@ -98,17 +102,11 @@ endif
 	rmdir $(DESTDIR)$(mandir)
 
 clean:
-	rm -f $(HTML_DIR)/*.html
-	rm -f $(MAN1_DIR)/*.1 $(MAN4_DIR)/*.4
-	rm -f $(SOURCE_DIR)/module.pod
-ifneq ($(wildcard $(MAN1_DIR)),)
-	rmdir $(MAN1_DIR)
-endif
-ifneq ($(wildcard $(MAN4_DIR)),)
-	rmdir $(MAN4_DIR)
-endif
-ifneq ($(wildcard $(MAN_DIR)),)
-	rmdir $(MAN_DIR)
+# do not clean generated docs if not in git repository
+ifeq ($(wildcard ../.git),../.git)
+	$(SPHINXBUILD) -M clean "$(SOURCE_DIR)" "$(BUILD_DIR)" $(SPHINXOPTS)
+	rm -f $(BUILD_DIR)/*.1.in
+	rmdir $(BUILD_DIR)
+	rm -f $(SOURCE_DIR)/version.py
 endif
-	rm -f diff_v3_v4.txt
-	rm -f pod*.tmp
+	rm -f $(BUILD_DIR)/*.1