From 7cfde7ca164038ee3f260adc325382e19d677f0d Mon Sep 17 00:00:00 2001 From: Scott Daniels Date: Mon, 30 Sep 2013 08:56:10 -0400 Subject: [PATCH] Added appendix which describes all commandline options for orchestrator.py 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 --- doc/source/ic_user/gen_cmdline_tex.ksh | 184 +++++++++++++++++++++++++ doc/source/ic_user/ic_user.tex | 22 +-- doc/source/ic_user/makefile | 24 +++- doc/source/ic_user/orch_cmdline.tex | 13 ++ doc/source/ic_user/prep.tex | 2 +- 5 files changed, 229 insertions(+), 16 deletions(-) create mode 100755 doc/source/ic_user/gen_cmdline_tex.ksh create mode 100644 doc/source/ic_user/orch_cmdline.tex diff --git a/doc/source/ic_user/gen_cmdline_tex.ksh b/doc/source/ic_user/gen_cmdline_tex.ksh new file mode 100755 index 0000000..e07cb53 --- /dev/null +++ b/doc/source/ic_user/gen_cmdline_tex.ksh @@ -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 diff --git a/doc/source/ic_user/ic_user.tex b/doc/source/ic_user/ic_user.tex index 8de617c..d6350f0 100644 --- a/doc/source/ic_user/ic_user.tex +++ b/doc/source/ic_user/ic_user.tex @@ -1,5 +1,5 @@ %% Mnemonic: ic_user.tex -%% Abstract: LaTex source for the inception cloud user doc. +%% Abstract: LaTex source for the inception cloud user doc. %% Date: 26 August 2013 %% Author: E. Scott Daniels %% Mods: 01 Sep 2013 : Converted from {X}fm source @@ -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} diff --git a/doc/source/ic_user/makefile b/doc/source/ic_user/makefile index 3b718c4..74987c8 100644 --- a/doc/source/ic_user/makefile +++ b/doc/source/ic_user/makefile @@ -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: diff --git a/doc/source/ic_user/orch_cmdline.tex b/doc/source/ic_user/orch_cmdline.tex new file mode 100644 index 0000000..80eeeec --- /dev/null +++ b/doc/source/ic_user/orch_cmdline.tex @@ -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 + diff --git a/doc/source/ic_user/prep.tex b/doc/source/ic_user/prep.tex index c3f80d6..5aed3c5 100644 --- a/doc/source/ic_user/prep.tex +++ b/doc/source/ic_user/prep.tex @@ -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.