Browse Source

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
Scott Daniels 5 years ago
parent
commit
7cfde7ca16

+ 184
- 0
doc/source/ic_user/gen_cmdline_tex.ksh View File

@@ -0,0 +1,184 @@
1
+#!/usr/bin/env ksh
2
+# This really should be executed with kshell, but it should be simplistic enough for bash.
3
+#	vi:sw=4 ts=4:
4
+
5
+# ---------------------------------------------------------------------------------------
6
+#
7
+#	Mnemonic:	gen_cmdline_tex.ksh
8
+# 	Abstract:	This script susses out the help messages from the desired .py
9
+#				file. code and generates the bulk of the cmdline.tex file.
10
+#				We assume that this is driven by mk or make during the build
11
+#				document process. Input is the name of the .py file (relative path
12
+#				under the source root) that should be parsed, the output file name,
13
+#				and the target list name within the source to pull the data from.
14
+#	Date:		14 Oct 2013
15
+#	Author:		E. Scott Daniels
16
+#
17
+# ---------------------------------------------------------------------------------------
18
+
19
+
20
+# we assume that the root of the source tree contains the doc directory, and that no
21
+# directoy under doc has a doc directory. Function finds the top of the source tree
22
+# so that we can locate the desired file.
23
+function find_root
24
+{
25
+	typeset pd=$PWD
26
+
27
+	while [[ ! -d $pd/doc ]]
28
+	do
29
+		if [[ $pd == ""  ]]
30
+		then
31
+			echo "$argv0: unable to find source root  [FAIL]"
32
+			exit 1
33
+		fi
34
+		pd=${pd%/*}
35
+
36
+	done
37
+
38
+	echo "$pd"
39
+}
40
+
41
+
42
+argv0="${0##*/}"				# simple name for error messages
43
+
44
+if [[ $1 != "/"* ]]
45
+then
46
+	input=$(find_root)/$1		# py soruce file we'll parse
47
+else
48
+	input=$1
49
+fi
50
+output=$2
51
+opt_target="$3"				# string that sets off the array assignment in the source code
52
+
53
+if [[ ! -f $input ]]
54
+then
55
+	echo "$argv0: cannot find input file: $input   [FAIL]"
56
+	exit 1
57
+fi
58
+
59
+if [[ -z opt_target ]]
60
+then
61
+	echo "$argv0: missing command line parm:  option target list  [FAIL]"
62
+	exit 1
63
+fi
64
+
65
+# we assume the syntax is predictable based on the cfg object and that parameters on the
66
+# python calls are all name=value pairs with the exception of the first.
67
+sed -r 's/^[ 	]+//' $input | awk -v squote="'" -v target=$opt_target '
68
+	BEGIN {
69
+		oidx = 0;
70
+	}
71
+
72
+	function split_first( haystack, user_target, needle,		n )
73
+	{
74
+		if( (n = index( haystack, needle )) > 0 )
75
+		{
76
+			user_target[1] = substr( haystack, 1, n-1 );
77
+			user_target[2] = substr( haystack, n+1 );
78
+		}
79
+		else
80
+		{
81
+			user_target[1] = haystack;
82
+			user_target[2] = "";
83
+		}
84
+	}
85
+
86
+	# we assume str contains one or more key=value pairs separated with commas and with
87
+	# potenital closing ) and ].
88
+	function parse_rest( str, 		a, b )
89
+	{
90
+		while( str != "" )
91
+		{
92
+			if( substr( str, 1, 1 ) == "]" )
93
+			{
94
+				snarf = 0;						# should not be needed, but prevent accidents
95
+				exit( 0 );						# we will only capture the first list
96
+			}
97
+
98
+			if( substr( str, 1, 1 ) == ")"  || substr( str, 1, 1 ) == "," || substr( str, 1, 1 ) == " " || substr( str, 1, 1 ) == "\t" )  # skip insignificant stuff
99
+				str = substr( str, 2 );
100
+			else
101
+			if( ! index( str, "=" ) )			# assume bloody split string to pretend we are in the 80s and have just 24x80 crts again
102
+			{
103
+				split_first( str, a, "," );
104
+				gsub( squote, "", a[1] );
105
+				data[pname, dname] = data[pname, dname] a[1];		# join
106
+				str = a[2];
107
+			}
108
+			else
109
+			{
110
+				split_first( str, a, "=" );
111
+				if( substr( a[2], 1, 1 ) == squote )
112
+					split_first( substr( a[2], 2), b, squote );
113
+				else
114
+				{
115
+					if( substr( a[2], 1, 1 ) == "[" ) 		# probalby an array used as a default -- snarf the whole thing
116
+					{
117
+						split_first( a[2], b, "]" );
118
+						b[1] = b[1] "]";					# add the close back that split stripped
119
+					}
120
+					else
121
+						split_first( a[2], b, "," );
122
+				}
123
+
124
+				data_seen[a[1]] = 1;
125
+				dname = a[1];
126
+				data[pname, dname] = b[1];
127
+
128
+				if( substr( b[2], 1, 1 ) == "," )
129
+					str = substr( b[2], 2 );
130
+				else
131
+					str = b[2];
132
+			}
133
+		}
134
+	}
135
+
136
+	!snarf {
137
+		snarf = match( $0, target ".*=.*[[]" ) > 0 ? 1 : 0;
138
+		next;
139
+	}
140
+
141
+	/cfg\..*Opt\(/ {
142
+		split_first( $0, a, "(" );
143
+
144
+		split_first( a[2], b, "," );
145
+		gsub( squote, "", b[1] );
146
+		pname = b[1];
147
+		order[oidx++] = pname;				# output order will match the order defined in the code
148
+		if( b[2] != "" )
149
+			parse_rest( b[2] );
150
+
151
+		next;
152
+	}
153
+
154
+	snarf {
155
+		parse_rest( $0 );
156
+		next;
157
+	}
158
+
159
+	END {
160
+		for( i = 0; i < oidx; i++ )
161
+		{
162
+			pname = order[i];
163
+
164
+			if( data[pname, "short"] != "" )
165
+				printf( "\\dlitemcw{-%s\n\n--%s} {\n", data[pname, "short"], pname );
166
+			else
167
+			{
168
+				printf( "\\vspace{5pt}\n" );
169
+				printf( "\\dlitemcw{--%s} {\n",  pname );
170
+			}
171
+
172
+			gsub( "\.$", "", data[pname, "help"] );			# on the off chance that the programmer uses proper punctuation,
173
+			printf( "%s.\n", data[pname, "help"] );			# but seems they dont, so we assume we always need to add it.
174
+			if( data[pname, "required"] == "True" )
175
+				printf( "This parameter is required.\n" );
176
+			if( data[pname, "default"] != "" && data[pname, "default"] != "None" )
177
+				printf( "When not supplied the default used is: %s.\n", data[pname, "default"] );	# latex canNOT handle verb here :(
178
+			printf( "}\n\n" );
179
+		}
180
+	}
181
+' |sed 's/_/\\_/g' >$output
182
+
183
+
184
+exit 0

+ 12
- 10
doc/source/ic_user/ic_user.tex View File

@@ -1,5 +1,5 @@
1 1
 %% Mnemonic:	ic_user.tex
2
-%% Abstract:	LaTex source for the inception cloud user doc. 
2
+%% Abstract:	LaTex source for the inception cloud user doc.
3 3
 %% Date:		26 August 2013
4 4
 %% Author:		E. Scott Daniels
5 5
 %% Mods:		01 Sep 2013  : Converted from {X}fm source
@@ -31,17 +31,19 @@
31 31
 \newpage
32 32
 \appendix
33 33
 \input{examples}
34
+\newpage
35
+\input{orch_cmdline}
34 36
 %
35 37
 % ---------- end matter ------------------------
36 38
 %
37
-\tiny
38
-\vspace{3in}
39
-\noindent
40
-\rule{\linewidth}{1 pt} 
41
-\dlbeg{0.3in}
42
-\dlitem{Original:}{August 26, 2013}
43
-\dlitem{Revised:}{\today}
44
-\dlitem{Source:}{ic\_user.tex}
45
-\dlend
39
+%\tiny
40
+%\vspace{3in}
41
+%\noindent
42
+%\rule{\linewidth}{1 pt}
43
+%\dlbeg{0.3in}
44
+%\dlitem{Original:}{August 26, 2013}
45
+%\dlitem{Revised:}{\today}
46
+%\dlitem{Source:}{ic\_user.tex}
47
+%\dlend
46 48
 
47 49
 \end{document}

+ 19
- 5
doc/source/ic_user/makefile View File

@@ -1,4 +1,5 @@
1
-# 
1
+# vim:sw=4 ts=4:
2
+
2 3
 # Abstract:	makes all pdf files. make promote will copy the final .pdf files to the top level source
3 4
 #			make clean cleans up tex detritus, make nuke scrubs everything away.
4 5
 # Date: 	26 August 2013
@@ -8,20 +9,33 @@
8 9
 
9 10
 include ../global.make	# meta stuff
10 11
 
11
-fig_list = inception_final start_overview inception_planes
12
-sec_list = overview prep running using examples
12
+#	we'll default to bash -- if no MK_SHELL was supplied we'll assume a sparse system that doesn't have ksh either; sigh.
13
+ifeq ($(SHELL),sh)
14
+	MODERN_SHELL := bash
15
+endif
13 16
 
17
+fig_list = inception_final start_overview inception_planes
18
+sec_list = overview prep running using examples orch_cmdline
19
+dyn_list = dyn_cmdline
14 20
 
15 21
 build_list = ic_user.pdf
16 22
 all:: $(build_list)
17 23
 
18
-promote::	$(build_list)
24
+
25
+
26
+# generate the body of the command line options section
27
+.PHONY: dyn_cmdline.tex
28
+dyn_cmdline.tex:
29
+	$(MODERN_SHELL) gen_cmdline_tex.ksh inception/orchestrator.py  dyn_cmdline.tex orchestrator_opts
30
+
31
+
32
+promote:	$(build_list)
19 33
 	for f in $(build_list);\
20 34
 	do\
21 35
 		cp $$f ../;\
22 36
 	done
23 37
 
24
-ic_user.pdf:: ic_user.tex $(sec_list:%=%.tex) $(fig_list:%=%.pdf)
38
+ic_user.pdf: ic_user.tex $(sec_list:%=%.tex) $(dyn_list:%=%.tex) $(fig_list:%=%.pdf)
25 39
 
26 40
 # everything except final doc files
27 41
 clean:

+ 13
- 0
doc/source/ic_user/orch_cmdline.tex View File

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

+ 1
- 1
doc/source/ic_user/prep.tex View File

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

Loading…
Cancel
Save