Commit 40648c90 authored by Nick R. Papior's avatar Nick R. Papior
Browse files

Added Docs/release.sh script for easy creation of tar.gz

This script enables easier release tar.gz files with a consistent
format.
The main functionality is that it will create a folder:
   siesta-releases
in the main folder where it will create a branch at the specified
tag. It will subsequently build the documentation and create
any necessary changes to the code that is necessary before
making the code available publicly.

This script is provided by Nick R. Papior
parent 66a3de1f
Full restructure of the TeX documentation method.
This will accommodate a complete environment in TeX for more stringent
formatting of the documentation.
This will be a work-in-progress as not all flags are transferred but
will be eventually.
# Splitting of siesta and tbtrans documentation
The documentation also splits the tbtrans and siesta manual in two.
This is to accommodate the tbtrans as a stand-alone program (which it
now is).
The siesta manual links to the tbtrans manual (if it is in the same folder).
## fdf-options
The fdf-options should be documented as these examples:
\begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$>
\end{fdfentry}
\begin{fdflogicalT}{FDF.Name!Logical.Default.True}
\end{fdflogicalT}
\begin{fdflogicalF}{FDF.Name!Logical.Default.False}
\end{fdflogicalF}
For instance
\begin{fdfentry}{FDF.Name!SubName}[real]<$0.1$>
Description of the FDF flag.
\end{fdfentry}
To make examples of fdf flags, use this enviroment (which is a VERBATIM environment
in disguise):
\begin{fdfexample}
\end{fdfexample}
Similarly for shell examples:
\begin{shellexample}
\end{shellexample}
Note that the internals of the commands will automatically convert:
FDF.Name!SubName into FDF.Name.SubName but will use the ! when adding the
flag to the index files. One may reference fdf flags in the text via:
\fdf{FDF.Name!SubName} which will 1) add the place in the file to the index (for back-referencing),
and 2) transform the shown text as a link to the block where it is created.
This will make reading the manual much easier as one may press the flags
and automatically be moved to the location in the PDF (if the viewer supports it).
If one does not wish to create a link, one may use the starred variant of the
\fdf* command.
## Files
Files in the manual may be referenced using: \file{full-file-name} and/or
\sysfile{file-ending}, where the latter is a shorthand for \file{<SystemLabel>.file-ending}.
## Manual indices
The new siesta documentation now splits the index into 3, 1) contains generic
index entries, 2) all fdf-flags, and 3) the siesta files.
To add specific entries in the regular index, simply use the \index command. To add to the
fdf index, use \fdfindex. For adding to the file index, use \fileindex.
Secondly this branch introduces the release.sh script which enables an
easy release tarball creation.
We encourage that it is called with these options:
./Docs/release.sh --prev-tag siesta-3.2 --tag 4.0-release --out siesta-4.0
To create the release of version 4.0.
The previous tag is used to generate a CHANGES and CHANGES_DETAILED file
which contain the entire log of the commit messages.
\ No newline at end of file
#!/bin/bash
# Script for preparing a release
# of SIESTA.
# Script-author:
# Nick R. Papior, 2016
#
# We encourage the use such as this:
# To create the 4.0 release, we would advocate performing
# this command:
# ./release.sh --prev-tag siesta-3.2 --tag 4.0-release \
# --out siesta-4.0
# which creates the file:
# siesta-releases/siesta-4.0.tar.gz
# We encourage that the prev-tag is ALWAYS the previous
# stable release tag.
# This ensures a consistent changes file shipped with
# the tar-file.
# I.e. for the 4.1 release, the command would be:
# ./release.sh --prev-tag 4.0-release --tag 4.1-release \
# --out siesta-4.1
# This may actually not be changed, but is useful
# throughout.
main_dir=`bzr root`
pushd $main_dir
# First we setup the default options
_reldir=siesta-releases
# Get default tags...
_prev_tag=`bzr tags --sort=time | tail -2 | head -1 | awk '{print $1}'`
_tag=`bzr tags --sort=time | tail -1 | awk '{print $1}'`
# Get default output file (siesta-<>.tar.gz)
_out=siesta-${_tag//-release/}
_out=${_out//-rel/}
_out=${_out//release-/}
_out=${_out//rel-/}
function _has_tag {
local tag=$1
shift
local ret=1
for T in `bzr tags | awk '{print $1}'`
do
if [ "$tag" == "$T" ]; then
ret=0
fi
done
printf "%d" "$ret"
}
function _help {
local ret=$1
shift
echo "$0 creates a release of the SIESTA code at the tip-tag"
echo ""
echo "These options may be used to control the archive."
echo ""
echo " --prev-tag instead of selecting the second-latest tag, choose this tag as the"
echo " reference tag for creating a diff with regards to the --tag tag [bzr tags --sort=time]"
echo " --tag instead of selecting the latest tag, choose this tag as the"
echo " reference tag for creating a release archive [bzr tags --sort=time]"
echo " --out the default output file is siesta-<tag>.tar.gz."
echo " --help|-h show this help."
exit $ret
}
# First we check whether the release-manager has
# specified the tag that is going to be shipped.
while [ $# -gt 0 ]; do
opt=$1
shift
case $opt in
--tag)
_tag=$1
# Check that the tag exists
if [ $(_has_tag $_tag) -eq 1 ]; then
echo "$0 could not find tag: '$_tag' in the tags list."
echo "The available tags are:"
bzr tags | awk '{print " ",$1}'
exit 1
fi
shift
;;
--prev-tag)
_prev_tag=$1
# Check that the tag exists
if [ $(_has_tag $_prev_tag) -eq 1 ]; then
echo "$0 could not find tag: '$_prev_tag' in the tags list."
echo "The available tags are:"
bzr tags | awk '{print " ",$1}'
exit 1
fi
shift
;;
--out)
_out=$1
shift
;;
--help|-h)
_help 0
;;
esac
done
#
# The current procedure of releasing a SIESTA
# version is the following:
# 0. Create a temporary directory
# 1. Make the proper documentation
# 2. Create diff files (both detailed and non-detailed)
# 3. Go out of the top-directory to create the repository.
# Create a temporary work-directory
cd ../
# If the release already exists... Tell the user and quit
if [ -d $_reldir/$_tag ]; then
echo "The release has already been processed."
echo "Delete this folder:"
echo " rm -rf $(dirname $main_dir)/$_reldir/$_tag"
exit 1
fi
bzr branch $main_dir -r $_tag release-manager-$_tag
mkdir -p $_reldir
# Move the branch into the directory.
mv release-manager-$_tag $_reldir/$_tag
# Go into the release directory where all work will be done
pushd $_reldir
pushd $_tag
rel_dir=`bzr root`
# Create documentation
pushd Docs
# First create the screen variants...
make final-screen
# Then the regular documentation (for print)
make final
# Only retain the pdf files
make clean
# Go out of the documentation directory...
popd
# Create the two different CHANGES file
{
echo "##############################################"
echo " Changes between $_prev_tag and $_tag"
echo "##############################################"
echo ""
bzr log -r$_prev_tag..$_tag
} > CHANGES
{
echo "##############################################"
echo " Detailed Changes between $_prev_tag and $_tag"
echo "##############################################"
echo ""
bzr log -n 0 -r$_prev_tag..$_tag
} > CHANGES_DETAILED
# Return from the branch release
popd
# Tar the file
# In some future cases will the tag and out name
# be equivalent and we shouldn't delete what we should process!
if [ $_out != $_tag ]; then
rm -rf $_out
cp -rf $_tag $_out
fi
# Create the archive... (without any .bzr files)
tar --exclude '.bzr*' -czf $_out.tar.gz $_out
if [ $_out != $_tag ]; then
rm -rf $_out
fi
popd
......@@ -3555,14 +3555,14 @@ several orders of consistency cycles.
\end{fdfentry}
\begin{fdfentry}{SCF.Mix!First}[logical]<true|false>
\begin{fdflogicalT}{SCF.Mix!First}
\index{DM.MixSCF1@\fdf*{DM.MixSCF1}|see SCF.Mix.First}
Whether the first SCF should be mixed or it uses the output as input
in the next SCF step. It is generally advised to set this to true,
at least when restarting calculations.
\end{fdfentry}
\end{fdflogicalT}
In the following the density matrix ($\DM$) will be used in the
......
......@@ -32,6 +32,18 @@
}%
}
% Create shorthand commands for file-indices
\NewDocumentCommand\fileindex{ m o }
{%
\IfNoValueTF{#2}{%
%\index{#1@\fdf*{#1}}%
\sindex[sfiles]{#1}%
}{%
%\index{#1@\fdf*{#1}#2}%
\sindex[sfiles]{#1#2}%
}%
}
%%% Local Variables:
......
trunk-536-doc-25
trunk-536-doc-26
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment