x/inception
Code Issues Proposed changes

Added appendix which describes all commandline options for orchestrator.py

Browse Source 
In addition, one small typo was fixed in prep.tex

The bulk of the appendix section is automatically generated using the
sourece code rather than relying on cut/paste.

Change-Id: I9fb98f9845d42daa624f12521444d03acb942dea
This commit is contained in:
Scott Daniels 2013-09-30 08:56:10 -04:00
parent 4223996ab6
commit 7cfde7ca16
5 changed files with 229 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
doc/source/ic_user/gen_cmdline_tex.ksh Executable file
View File

@ -0,0 +1,184 @@
#!/usr/bin/env ksh
# This really should be executed with kshell, but it should be simplistic enough for bash.
# vi:sw=4 ts=4:
# ---------------------------------------------------------------------------------------
#
# Mnemonic: gen_cmdline_tex.ksh
# Abstract: This script susses out the help messages from the desired .py
# file. code and generates the bulk of the cmdline.tex file.
# We assume that this is driven by mk or make during the build
# document process. Input is the name of the .py file (relative path
# under the source root) that should be parsed, the output file name,
# and the target list name within the source to pull the data from.
# Date: 14 Oct 2013
# Author: E. Scott Daniels
#
# ---------------------------------------------------------------------------------------
# we assume that the root of the source tree contains the doc directory, and that no
# directoy under doc has a doc directory. Function finds the top of the source tree
# so that we can locate the desired file.
function find_root
{
typeset pd=$PWD
while [[ ! -d $pd/doc ]]
do
if [[ $pd == "" ]]
then
echo "$argv0: unable to find source root [FAIL]"
exit 1
fi
pd=${pd%/*}
done
echo "$pd"
}
argv0="${0##*/}" # simple name for error messages
if [[ $1 != "/"* ]]
then
input=$(find_root)/$1 # py soruce file we'll parse
else
input=$1
fi
output=$2
opt_target="$3" # string that sets off the array assignment in the source code
if [[ ! -f $input ]]
then
echo "$argv0: cannot find input file: $input [FAIL]"
exit 1
fi
if [[ -z opt_target ]]
then
echo "$argv0: missing command line parm: option target list [FAIL]"
exit 1
fi
# we assume the syntax is predictable based on the cfg object and that parameters on the
# python calls are all name=value pairs with the exception of the first.
sed -r 's/^[ ]+//' $input | awk -v squote="'" -v target=$opt_target '
BEGIN {
oidx = 0;
}
function split_first( haystack, user_target, needle, n )
{
if( (n = index( haystack, needle )) > 0 )
{
user_target[1] = substr( haystack, 1, n-1 );
user_target[2] = substr( haystack, n+1 );
}
else
{
user_target[1] = haystack;
user_target[2] = "";
}
}
# we assume str contains one or more key=value pairs separated with commas and with
# potenital closing ) and ].
function parse_rest( str, a, b )
{
while( str != "" )
{
if( substr( str, 1, 1 ) == "]" )
{
snarf = 0; # should not be needed, but prevent accidents
exit( 0 ); # we will only capture the first list
}
if( substr( str, 1, 1 ) == ")" || substr( str, 1, 1 ) == "," || substr( str, 1, 1 ) == " " || substr( str, 1, 1 ) == "\t" ) # skip insignificant stuff
str = substr( str, 2 );
else
if( ! index( str, "=" ) ) # assume bloody split string to pretend we are in the 80s and have just 24x80 crts again
{
split_first( str, a, "," );
gsub( squote, "", a[1] );
data[pname, dname] = data[pname, dname] a[1]; # join
str = a[2];
}
else
{
split_first( str, a, "=" );
if( substr( a[2], 1, 1 ) == squote )
split_first( substr( a[2], 2), b, squote );
else
{
if( substr( a[2], 1, 1 ) == "[" ) # probalby an array used as a default -- snarf the whole thing
{
split_first( a[2], b, "]" );
b[1] = b[1] "]"; # add the close back that split stripped
}
else
split_first( a[2], b, "," );
}
data_seen[a[1]] = 1;
dname = a[1];
data[pname, dname] = b[1];
if( substr( b[2], 1, 1 ) == "," )
str = substr( b[2], 2 );
else
str = b[2];
}
}
}
!snarf {
snarf = match( $0, target ".*=.*[[]" ) > 0 ? 1 : 0;
next;
}
/cfg\..*Opt\(/ {
split_first( $0, a, "(" );
split_first( a[2], b, "," );
gsub( squote, "", b[1] );
pname = b[1];
order[oidx++] = pname; # output order will match the order defined in the code
if( b[2] != "" )
parse_rest( b[2] );
next;
}
snarf {
parse_rest( $0 );
next;
}
END {
for( i = 0; i < oidx; i++ )
{
pname = order[i];
if( data[pname, "short"] != "" )
printf( "\\dlitemcw{-%s\n\n--%s} {\n", data[pname, "short"], pname );
else
{
printf( "\\vspace{5pt}\n" );
printf( "\\dlitemcw{--%s} {\n", pname );
}
gsub( "\.$", "", data[pname, "help"] ); # on the off chance that the programmer uses proper punctuation,
printf( "%s.\n", data[pname, "help"] ); # but seems they dont, so we assume we always need to add it.
if( data[pname, "required"] == "True" )
printf( "This parameter is required.\n" );
if( data[pname, "default"] != "" && data[pname, "default"] != "None" )
printf( "When not supplied the default used is: %s.\n", data[pname, "default"] ); # latex canNOT handle verb here :(
printf( "}\n\n" );
}
}
' |sed 's/_/\\_/g' >$output
exit 0

20
doc/source/ic_user/ic_user.tex
View File

@ -31,17 +31,19 @@
\newpage
\appendix
\input{examples}
\newpage
\input{orch_cmdline}
%
% ---------- end matter ------------------------
%
\tiny
\vspace{3in}
\noindent
\rule{\linewidth}{1 pt}
\dlbeg{0.3in}
\dlitem{Original:}{August 26, 2013}
\dlitem{Revised:}{\today}
\dlitem{Source:}{ic\_user.tex}
\dlend
%\tiny
%\vspace{3in}
%\noindent
%\rule{\linewidth}{1 pt}
%\dlbeg{0.3in}
%\dlitem{Original:}{August 26, 2013}
%\dlitem{Revised:}{\today}
%\dlitem{Source:}{ic\_user.tex}
%\dlend
\end{document}

24
doc/source/ic_user/makefile
View File

@ -1,4 +1,5 @@
#
# vim:sw=4 ts=4:
# Abstract: makes all pdf files. make promote will copy the final .pdf files to the top level source
# make clean cleans up tex detritus, make nuke scrubs everything away.
# Date: 26 August 2013
@ -8,20 +9,33 @@
include ../global.make # meta stuff
fig_list = inception_final start_overview inception_planes
sec_list = overview prep running using examples
# we'll default to bash -- if no MK_SHELL was supplied we'll assume a sparse system that doesn't have ksh either; sigh.
ifeq ($(SHELL),sh)
MODERN_SHELL := bash
endif
fig_list = inception_final start_overview inception_planes
sec_list = overview prep running using examples orch_cmdline
dyn_list = dyn_cmdline
build_list = ic_user.pdf
all:: $(build_list)
promote:: $(build_list)
# generate the body of the command line options section
.PHONY: dyn_cmdline.tex
dyn_cmdline.tex:
$(MODERN_SHELL) gen_cmdline_tex.ksh inception/orchestrator.py dyn_cmdline.tex orchestrator_opts
promote: $(build_list)
for f in $(build_list);\
do\
cp $$f ../;\
done
ic_user.pdf:: ic_user.tex $(sec_list:%=%.tex) $(fig_list:%=%.pdf)
ic_user.pdf: ic_user.tex $(sec_list:%=%.tex) $(dyn_list:%=%.tex) $(fig_list:%=%.pdf)
# everything except final doc files
clean:

13
doc/source/ic_user/orch_cmdline.tex Normal file
View File

@ -0,0 +1,13 @@
% command line options appendix
% this is a seliton. The meat of this section (the list) is pulled from the file that
% was created by the gen_ script.
\section{Orchestrator Options}
The following is a complete list of the command line options supported by \verb!orchestrator.!
\dlbeg{1.65in}
\input{dyn_cmdline.tex}
\dlend

2
doc/source/ic_user/prep.tex
View File

@ -119,7 +119,7 @@ The following lists the steps necessary to create the O/S images:
\begin{enumerate}
\item Ssh to the boot-up VM.
\item Copy inception utility scripts from the source installed on the workstation.
\item Run the script \verb!pre_switch_kernel.sh! to convert from a vertual kernel to a generic kernel.
\item Run the script \verb!pre_switch_kernel.sh! to convert from a virtual kernel to a generic kernel.
\item Wait for the VM to reboot and log in again.
\item Run the script \verb!pre_install_ovs.sh! to install open vswitch.
\item Using nova, or the dashboard, take a snapshot of the VM giving it an image name of XXX-gv.