Generation of docs on server does not work anymore

[averbraeck]

The generation of the readthedocs documentation for the djutils.org domain on the Delft servers has stopped. There are several reasons that need to be addressed.

Generation of the documentation was dependent on a number of commands to get information from the github servers:

• git ls-remote https://github.com/averbraeck/djutils refs/heads/main | awk '{print $1;}'
• wget https://raw.githubusercontent.com/averbraeck/djutils/main/mkdocs.yml
• svn export https://github.com/averbraeck/djutils/trunk/docs

The git ls-remote command still works, just like the wget command for https://raw.githubusercontent.com. The svn command, however, has been discontinued at github. See https://github.blog/2023-01-20-sunsetting-subversion-support.

A new script has to be generated that uses checkout of only one branch. Luckily, this can be done (for the main branch) with:

git clone -b main --single-branch https://github.com/averbraeck/djutils

[averbraeck]

The new checkout and compilation of the docs file looks as follows:

#!/bin/bash
CWD=~alexandv/djutils-docs
cd $CWD
export PATH=/data/home/alexandv/.local/bin:$PATH

# exit silently if we are already busy with this job
if [ -f "busy" ]; then
    exit 0
fi

# indicate we start a longer part of the job
touch busy

# grab the commit id from github
COMMIT_ID=`git ls-remote https://github.com/averbraeck/djutils refs/heads/main | awk '{print $1;}'`

# check if commit_id file exists and compare contents
if [ -f "commit_id" ]; then
  STORED_COMMIT_ID=`cat commit_id`
  if [[ $COMMIT_ID == $STORED_COMMIT_ID ]]; then
    echo "no updates to git"
    rm busy
    exit 0
  fi
fi
echo -n $COMMIT_ID > commit_id

# remove old folder (if exists)
rm -r -f djutils

# clone the main branch and move files to the right location
git clone -b main --single-branch https://github.com/averbraeck/djutils
retval=$?
if [ $retval -ne 0 ]; then
    echo "git clone did not succeed"
    cd $CWD
    rm busy commit_id
    exit 1
fi
cd djutils
cp docs/requirements.txt .

# compile the documentation from the docs folder to the site folder and copy
echo "Compile manual with MkDocs"
mkdocs build
retval=$?
if [ $retval -ne 0 ]; then
    echo "mkdocs build did not succeed"
    cd $CWD
    rm busy commit_id
    exit 1
fi

# copy the manual
echo "copy the manuals"
cd $CWD/djutils/site
rm -r -f /data/home/web/djutils.org/manual
mkdir /data/home/web/djutils.org/manual
cp -r . /data/home/web/djutils.org/manual

cd $CWD
rm busy
rm -f -r djutils

[averbraeck]

After this change, documentation generation on the server works again.