Use sphinx to generate the docs if available

If the sphinx-build command is installed use it to generate the
documentation from the reStructuredText source. Otherwise, use the
prebuild man pages.

.gitignore

@@ -36,3 +36,4 @@ Desktop.ini
 
 # Artifacts of the build and test process that should not be committed.
 build/
+src/cmd/ksh93/docs/_build/

.travis.yml

@@ -64,6 +64,9 @@ matrix:
         - os: osx
           compiler: clang
           before_install:
+              # Note that scripts/build-on-macos.sh will install the
+              # prerequisites such as Meson and Sphinx using HomeBrew. This is
+              # obviously different compared to the Linux platforms.
               - brew update
           env:
               # This variable is not required by macOS builds, but setting it for Travis dashboard.

scripts/build-on-macos.sh

@@ -2,6 +2,7 @@
 set -e
 
 brew install meson
+brew install sphinx
 
 . scripts/travis_common.sh
 

scripts/install_aux_files.sh

@@ -1,7 +1,7 @@
 #!/bin/sh
 #
-# Do installation steps that are hard to do via the standard Meson function
-# (e.g., `install_subdir()`).
+# Do installation steps that are hard to do via standard Meson functions such
+# as `install_subdir()`.
 #
 ksh_aux_dir="${MESON_INSTALL_DESTDIR_PREFIX}/share/ksh"
 ksh_man_dir="$ksh_aux_dir/man"
@@ -12,24 +12,22 @@ set -x
 mkdir -m 755 "$ksh_aux_dir"
 mkdir -m 755 "$ksh_man_dir"
 mkdir -m 755 "$ksh_man_dir/man1"
-cd "$ksh_man_src" || exit 99
 
-# At some point we'll want to uncomment this statement. Probably after we've
-# converted all the documentation to Sphinx format. At that point we'll want
-# to stop committing the `make man` artifacts when the docs are changed.
-# Instead, require that be done at install time.
-#
 # Note: I can't figure out how to make Sphinx `make man` emit the
 # documentation in the expected hierachy under the _build dir. Since we
-# currently only care about section one (i.e., command) documentation force it
-# to be installed in that directory.
-#
-# make man
+# currently only care about section one (i.e., command) documentation force
+# those docs to be installed in that directory.
+cd "$ksh_man_src" || exit 99
+if [ -n "$(command -v sphinx-build)" ]
+then
+    make clean
+    make man
+fi
 cp _build/man/*.1 "$ksh_man_dir/man1"
 
 # Old versions of Meson (e.g., 0.44) don't recognize the `install_mode` option
 # of functions like `install_subdir()` and don't use sensible default
-# permissions (e.g., no public read/execute). So try to ensure all the aux
-# files have reasonable permissions.
+# permissions (e.g., they have no public read/execute). So try to ensure all
+# the aux files have reasonable permissions.
 find "$ksh_aux_dir" -type d -print0 | xargs -0 chmod 755
 find "$ksh_aux_dir" -type f -print0 | xargs -0 chmod 644