percona-toolkit/util/write-user-docs

#!/usr/bin/env bash

# Usage: write-user-docs [FILES]
#
# This script writes/updates a tool's user documentation.  First, pod2rst
# is called to convert the file's POD to RST.  Then sphinx-build is called
# to convert the RST to HTML.
#
# RST files are written to docs/user/<tool>.rst, and HTML files are written
# to docs/user/html/<tool>.html.
#
# If no file are specified on the command line, then only the sections from
# docs/percona-toolkit.pod are written.
#
# If the env variable PERCONA_TOOLKIT_BRANCH is not set, then this script
# must be called from a directory in a branch.
#
# To rewrite all user docs from scratch:
#   rm -rf docs/user/*
#   util/write-user-docs bin/*
#
# Exits 0 on success, else 1 on warnings and errors.

# ############################################################################
# Standard startup, find the branch's root directory
# ############################################################################

exit_status=0

die() {
   echo "$1" >&2
   exit 1
}

warn() {
   echo "$1" >&2
   exit_status=1
}

cwd=$PWD
if [ -n "$PERCONA_TOOLKIT_BRANCH" ]; then
   BRANCH=$PERCONA_TOOLKIT_BRANCH
   cd $BRANCH
else
   while [ ! -f Makefile.PL ] && [ $(pwd) != "/" ]; do
      cd ..
   done
   if [ ! -f Makefile.PL ]; then
      die "Cannot find the root directory of the Percona Toolkit branch"
      exit 1
   fi
   BRANCH=`pwd`
fi
cd $cwd

# ############################################################################
# Paths
# ############################################################################

DOCS=$BRANCH/docs
RST=$DOCS/user
HTML=$RST/html
CONFIG=$BRANCH/config/sphinx-build

# ############################################################################
# Subroutines
# ############################################################################

write_rst() {
   local file="$1"
   if [ ! -f $file ]; then
      warn "$file does not exist"
      return
   fi
   local tool=$(basename $file)

   cat $file | pod2rst --title=$tool > $RST/$tool.rst
   exit_status=$(( exit_status | $? ))
   echo "Wrote $RST/$tool.rst"
}

write_index() {
   declare -a section_filenames
   local i=0

   sections=$(grep '^=head1' $DOCS/percona-toolkit.pod | grep -v "NAME" | sed -e 's/=head1 //' -e 's/ /_/g')
   for section in $sections; do
      header=$(echo $section | sed -e 's/_/ /g')

      if [ $section = "DESCRIPTION" ]; then
         filename="index"
      else
         filename=$(echo $section | sed -e 's/,//g' | tr "[:upper:]" "[:lower:]");
         section_filenames[$i]=$filename
         i=$(($i + 1))
      fi

      $BRANCH/util/extract-text $DOCS/percona-toolkit.pod "^=head1 $header" "^=head1|=cut" > /tmp/$filename.pod
      if [ $section = "DESCRIPTION" ]; then
         sed -i.bak -e 's/DESCRIPTION/Percona Toolkit Documentation/' /tmp/$filename.pod
      fi
      cat /tmp/$filename.pod | pod2rst | sed -e 's/.. highlight:: perl//g' > /tmp/$filename.tmp
      cat -s /tmp/$filename.tmp > $RST/$filename.rst
      rm /tmp/$filename.pod
      rm /tmp/$filename.tmp
      echo "Wrote $RST/$filename.rst"
   done

   echo ".. toctree::"    >> $RST/index.rst
   echo "   :maxdepth: 2" >> $RST/index.rst
   echo                   >> $RST/index.rst
   for section_filename in "${section_filenames[@]}"; do
      echo "   $section_filename" >> $RST/index.rst
   done

   echo "   release_notes" >> $RST/index.rst

   echo ".. toctree::" >> $RST/tools.rst
   echo "   :hidden:"  >> $RST/tools.rst
   echo                >> $RST/tools.rst
   local tools=$(grep '^pt-' $RST/tools.rst)
   for tool in $tools; do
      echo "   $tool" >> $RST/tools.rst
   done

   sed -e 's/^\(pt-.*\)/:doc:`\1`/g' -i.bak $RST/tools.rst
   rm $RST/*.bak
}

# ############################################################################
# Script starts here
# ############################################################################

WRITE=${WRITE:-1}
if [ $WRITE -eq 1 ]; then
   if [ $# -gt 0 ]; then
      for tool; do
         write_rst $tool
      done
   fi

   if [ ! -f "$RST/index.rst" ] || [ "$DOCS/percona-toolkit.pod" -nt "$RST/index.rst" ]; then
      write_index
   fi

   if [ ! -f "$RST/release_notes.rst" ] || [ "$DOCS/release_notes.rst" -nt "$RST/release_notes.rst" ]; then
      cp $DOCS/release_notes.rst $RST/
      echo "Wrote $RST/release_notes.rst"
   fi
fi

BUILD=${BUILD:-1}
if [ $BUILD -eq 1 ]; then
   # -W treats warnings as errors; remove it to ignore warnings if you must.
   sphinx-build -N -W -c $CONFIG -b html $RST $HTML
   exit_status=$(( exit_status | $? ))
fi

exit $exit_status