Draft documents for L10N

This page is obsolete
Use the instructions at Publishing draft documentation instead

For this release, we told the translation team we would do nightly builds of the documents so they could see whether they had any errors. Building and pushing it up to fedorapeople isn't hard, but it helps if we can automate it.

David Nalley asked me to document the way I automate the production of draft documents for translation. In addition, Ricky Zhou has provided us a space on fedorapeople to consolidate these draft documents.

The documents on fp.o still count against your quota, so if your Guide is pretty large you probably want to ask that your quota be increased to account for it.

The draft documents appear at: http://fedorapeople.org/groups/docs/

Make a directory for your guide in /srv/groups/docs on fedorapeople. Then make a symlink from your fedorapeople space to that directory. In my case, for example,

 cd public_html/Download
 ln -s /srv/groups/docs/release-notes F13

I then run the following script on my crontab:

#!/bin/sh
#
#  Script to build all languages of the release notes and
#  push them up to fedorapeople.org
#
# ----------------------------------------------------------
# Modify the following variables for your situation
#
# List of files/subdirectories to ignore
NOLANGS="build tmp pot po publican.cfg README"
# Scratch directory on local machine for work - autogenerated
WORKDIR=$(mktemp -d)
# User on fedorapeople
USER="jjmcd"
# Directory on fedorapeople
TARGET="public_html/Download/F13"
# Document to build *** NOTE ** If your document is not
# in the docs/ subtree in git, you will need to modify
# the git clone statement below.
DOC="release-notes"
# Branch for translations
BRANCH="f13"
#
# End of variables to modify
# ----------------------------------------------------------
#
# Move to scratch directory
cd $WORKDIR
# Let's check how long this takes
 echo "Start " date >time.txt
git clone git://git.fedorahosted.org/git/docs/$DOC.git
pushd $DOC
if [ "$BRANCH" != "master" ]; then
    git checkout --track -b $BRANCH origin/$BRANCH
else
    git checkout master  # Just to be pedantic
fi
# For all subdirectories
for LANG in * ; do
  # Figure out whether this one is one of those to ignore
  DOIT=1
  for TEST in $NOLANGS
    do
      if [ $LANG == $TEST ] ; then
        DOIT=0
      fi
    done
  # Do this directory
  if [ $DOIT == 1 ]
    then
      echo "        " $LANG
      # Build the html
      publican build -l $LANG -f html 2>../$LANG.log
      # Blow away the old copy
      ssh $USER@fedorapeople.org rm -Rf $TARGET/$LANG
      # Make a new directory
      ssh $USER@fedorapeople.org mkdir $TARGET/$LANG
      # Copy up the html
      scp -r tmp/$LANG/html/* \
        $USER@fedorapeople.org:$TARGET/$LANG/
      # And the log file
      scp ../$LANG.log $USER@fedorapeople.org:$TARGET/$LANG/
    fi
done
popd
# And now the finish time
echo "  End " date >>time.txt

(the time stuff is only because I wanted to keep an eye on the build time; I was running this very frequently in the last days before we built the RPM.

Notice that you will need to edit the top few lines to fit your particular situation. Also note that if your guide is not one of those in the docs/ subtree on git (Virtualization_Guide, amateur-radio-guide, documentation-guide, possibly others) you will need to edit the git clone statement to remove the docs/.

The script builds one language at a time, which slows down building considerably since Publican takes advantage of knowing that some of it's work applies to all languages. However, if you build all languages at once then an error on one can prevent many others from being done. Also, doing one at a time gives a chance to have an error log for each language. If the build failed for a language, the log will be placed on fp.o, the last line of that log being the offending statement.

Once you have tested the script for your document, you can put it on the crontab and updated copies will appear.