Wiki source code of EOModelDoc

Last modified by Theodore Petrosky on 2012/02/11 13:36

version	line-number	content
44.1	1	== Contents ==
	2
50.1	3	[[#Overview>>doc:\|\|anchor="Overview"]]
	4	[[#Future Plans>>doc:\|\|anchor="Future Plans"]]
	5	[[#Download and Example Output>>doc:\|\|anchor="Download and Example Output"]]
	6	[[#Usage>>doc:\|\|anchor="Usage"]]
	7	[[#Running from Ant>>doc:\|\|anchor="Running from Ant"]]
	8	[[#Template Files>>doc:\|\|anchor="Template Files"]]
	9	[[#Alternate Templates>>doc:\|\|anchor="Alternate Templates"]]
44.1	10
16.1	11	== Overview ==
	12
50.1	13	EOModelDoc is a command line tool to generate HTML documentation of a set of EOModels. It is a replacement for [[EOReporter>>url:http://www.rubicode.com/Software/EOReporter/\|\|shape="rect"]] (which will not work on Leopard and newer releases of OS X). EOModelDoc was funded by the Apple iTunes Store and released to the community.
16.1	14
54.1	15	On the WOLips side, from version 3.3.x, [[Entity Modeler>>doc:documentation.Home.Entity Modeler.WebHome]] has a Documentation tab on all of the elements of a model that lets you record HTML documentation for your model, entities, attributes, etc. There is even an HTML preview. You can then run eomodeldoc to produce documentation much like javadoc for your model.
16.1	16
	17	== Future Plans ==
	18
50.1	19	From Mike Schrag: //There's not a nice build process for this one either, yet, because it includes all of the eclipse dependencies in the single jar. Eventually I'll make this nicer and include it actually inside of Eclipse. There are also modifications to the ERNeutralLook coming soon that will display popup help for you models based on the model documentation.//
16.1	20
	21	== Download and Example Output ==
	22
50.1	23	[[Download EOModelDoc jar>>url:http://wocommunity.org/documents/tools/eomodeldoc.jar\|\|shape="rect"]]
32.1	24
50.1	25	This is an example of the current state of eomodeldoc (the default templates are not done, but it will give you an idea of what it can do). The templates are all Velocity-based, and you can override them with custom versions. This was run in the BugTracker project folder. This model does not have documentation added to it with the new Entity Modeler yet, so it looks a little more bare than it would if it was documented properly. I'll probably document it just to have a full example to show.
	26	[[View Example Output>>url:http://webobjects.mdimension.com/wolips/support/eomodeldoc_example/\|\|shape="rect"]]
32.1	27
	28	== Usage ==
	29
34.1	30	The command line syntax of for EOModelDoc:
	31
52.1	32	{{code language="none"}}
	33	java -jar eomodeldoc.jar -output /path/to/output/folder [-model /path/to/model.eomodeld]* [-modelgroup /path/to/working/dir] [-templates /path/to/templates] [-entityURLTemplate "http://domain/path/to/JavaDocs/$entity.classNamePath.html
	34	{{/code}}
34.1	35
50.1	36	\|=(((
	37	Parameter
	38	)))\|=(((
	39	Usage / Function
	40	)))
	41	\|(((
	42	output
	43	)))\|(((
	44	Path to the directory where the output HTML files will be written.
	45	)))
	46	\|(((
	47	model
	48	)))\|(((
	49	Path to one model to generate documentation for. This parameter can be used multiple times, once for each model.
	50	)))
	51	\|(((
	52	modelgroup
	53	)))\|(((
	54	The path to an Eclipse or IDEA project. All models listed in the project will be documented. This defaults to the current working directory.
	55	)))
	56	\|(((
	57	templates
	58	)))\|(((
	59	Path to the directory where the Velocity templates are stored. See the [[#Template Files>>doc:\|\|anchor="Template Files"]] section below for details on these templates. If this is not specified, the default templates inside the eomodeldoc.jar file will be used.
	60	)))
	61	\|(((
	62	entityURLTemplate
	63	)))\|(((
	64	URL to the JavaDocs for the classes in the model. This is used to create links from the EOModel documentation to the JavaDoc documentation. The dots in the classpath are replaced with "/" when the path is generated.
	65	)))
44.1	66
	67	=== Notes ===
	68
50.1	69	* Only {{code language="none"}}-output{{/code}} is required
	70	* Usually only one of {{code language="none"}}-modelGroup{{/code}} or {{code language="none"}}-model{{/code}} is used (i.e. not both at the same time)
	71	* The {{code language="none"}}-templates{{/code}} path only needs to point the the templates that you have changed. If any templates are not found on that path, the defaults from the jar are used.
	72	* For {{code language="none"}}-entityURLTemplate{{/code}} the [[http:~~/~~/domain/path/to/JavaDocs/>>url:http://domain/path/to/JavaDocs/\|\|shape="rect"]]{{code language="none"}}{{/code}} the path to the index.html file that JavaDoc generates. It will be something like [[http:~~/~~/developer.apple.com/documentation/MacOSXServer/Reference/WO54_Reference/>>url:http://developer.apple.com/documentation/MacOSXServer/Reference/WO54_Reference/\|\|shape="rect"]]{{code language="none"}}{{/code}}. If the EOModelDocs and JavaDocs are on the same server, you can use absolute or relative paths instead of a full URL:[[http:~~/~~/developer.apple.com/documentation/MacOSXServer/Reference/WO54_Reference/>>url:http://developer.apple.com/documentation/MacOSXServer/Reference/WO54_Reference/\|\|shape="rect"]]{{code language="none"}}{{/code}}
44.1	73
34.1	74	=== Usage Examples ===
	75
	76	Document one model:
	77
	78	{{code}}
	79
44.1	80	java -jar /path/to/eomodeldoc.jar -model /path/to/model.eomodeld -output /tmp/eomodeldoc
34.1	81
	82	{{/code}}
	83
44.1	84	Document all models based on the Eclipse or IDEA project definition:
32.1	85
34.1	86	{{code}}
	87
44.1	88	java -jar /path/to/eomodeldoc.jar -modelgroup /path/to/project -output /tmp/eomodeldoc
34.1	89
	90	{{/code}}
	91
	92	Document all models based on the Eclipse/IDEA project definition (when current working directory is the top level of the project):
	93
	94	{{code}}
	95
44.1	96	java -jar /path/to/eomodeldoc.jar -output /tmp/eomodeldoc
34.1	97
	98	{{/code}}
	99
44.1	100	== Running from Ant ==
	101
50.1	102	Note: do not put this jar on your classpath! Chaos and Other Bad Things may ensue.
44.1	103
50.1	104	There is no Ant task (yet) for EOModelDoc. You can run it with an {{code language="none"}}java{{/code}} task following this pattern:
44.1	105
52.1	106	{{code 0="xml"}}<java jar="/path/to/eomodeldoc.jar"
44.1	107	fork="true"
	108	maxmemory="256m">
	109	<arg value="-output" />
	110	<arg value="/path/to/output/folder" />
	111	<arg value="-modelgroup" />
	112	<arg value="/path/to/working/dir" />
	113	<arg value="-templates" />
	114	<arg value="/path/to/templates" />
	115	<arg value="-entityURLTemplate" />
	116	<arg value="http://whatever?$${entity.classNamePath}.html" />
52.1	117	</java>{{/code}}
44.1	118
50.1	119	{{code 0="xml"}}
44.1	120
	121	<java jar="/path/to/eomodeldoc.jar"
	122	fork="true"
	123	maxmemory="256m">
	124	<arg value="-output" />
	125	<arg value="/path/to/output/folder" />
	126	<arg value="-model" />
	127	<arg value="/path/to/modelA.eomodeld" />
	128	<arg value="-model" />
	129	<arg value="/path/to/modelB.eomodeld" />
	130	<arg value="-model" />
	131	<arg value="/path/to/modelC.eomodeld" />
	132	<arg value="-templates" />
	133	<arg value="/path/to/templates" />
	134	<arg value="-entityURLTemplate" />
	135	<arg value="http://whatever?$${entity.classNamePath}.html" />
	136	</java>
	137
	138	{{/code}}
	139
	140	If you include this in the build.xml file in the project, it can be as simple as:
	141
50.1	142	{{code 0="xml"}}
44.1	143
	144	<java jar="/path/to/eomodeldoc.jar"
	145	fork="true"
	146	maxmemory="256m">
	147	<arg value="-output" />
	148	<arg value="Documentation" />
	149	<arg value="-modelgroup" />
	150	<arg value="." />
	151	</java>
	152
	153	{{/code}}
	154
34.1	155	== Template Files ==
	156
50.1	157	Default templates are included in the eomodeldoc.jar file. You can extract these templates to use as a basis for your own templates with this command:
34.1	158
	159	{{code}}
	160
	161	unzip /path/to/eomodeldoc.jar .vm -x "/*"
	162
	163	{{/code}}
	164
52.1	165	See the [[EOGenerator template documentation>>doc:WOL.Home.EOGenerator.EOGenerator Templates and Additions.WebHome]] documentation for information on customizing these templates. The {{code language="none"}}-templates{{/code}} path only needs to point the the templates that you have changed. If any templates are not found on that path, the defaults from the jar are used.
34.1	166
	167	The templates and their function are:
	168
50.1	169	\|=(((
	170	Template Name
	171	)))\|=(((
	172	Usage / Function
	173	)))
	174	\|(((
	175	indexModels.html.vm
	176	)))\|(((
	177	Left pane index of all models.
	178	)))
	179	\|(((
	180	indexOverview.html.vm
	181	)))\|(((
	182	Left pane index of the contents of all models (e.g. list of entities and stored procedures).
	183	)))
	184	\|(((
	185	modelOverview.html.vm
	186	)))\|(((
	187	Left pane index of the contents of one model (e.g. list of entities and stored procedures).
	188	)))
	189	\|(((
	190	indexContent.html.vm
	191	)))\|(((
	192	Main frame description of each model and contents of each model (e.g. list of entities and stored procedures).
	193	)))
	194	\|(((
	195	modelContent.html.vm
	196	)))\|(((
	197	Main frame contents of one model (list of entities and stored procedures).
	198	)))
	199	\|(((
	200	entityContent.html.vm
	201	)))\|(((
	202	Main frame contents for one Entity
	203	)))
	204	\|(((
	205	storedProcedureContent.html.vm
	206	)))\|(((
	207	Main frame contents for one stored procedure.
	208	)))
	209	\|(((
	210	index.html.vm
	211	)))\|(((
	212	Top level index.html file defining frameset. You probably won't need to modify this.
	213	)))
	214	\|(((
	215	prototype.js.vm
	216	)))\|(((
	217	[[Prototype>>url:http://www.prototypejs.org/learn\|\|shape="rect"]] JavaScript file so that the generated documentation can use Ajax whizziness. You probably won't need to modify this.
	218	)))
	219	\|(((
	220	eomodeldoc.css.vm
	221	)))\|(((
	222	CSS file that controls what the generate output looks like.
	223	)))
	224	\|(((
	225	eomodeldoc.js.vm
	226	)))\|(((
	227	JavaScript file that cleans up the display. You probably won't need to modify this.
	228	)))
	229
34.1	230	Some pictures will illustrate this:
	231
	232	----
	233
50.1	234	[[image:attach:EOModelDocTemplates1.png]]
34.1	235
	236	----
	237
50.1	238	[[image:attach:EOModelDocTemplates2.png]]
34.1	239
	240	----
	241
50.1	242	[[image:attach:EOModelDocTemplates3.png]]
34.1	243
	244	----
42.1	245
44.1	246	== Alternate Templates ==
	247
50.1	248	Have some interesting templates to share? Add them as attachements and link them here.
44.1	249
	250	=== Template Mark I from Chuck ===
	251
50.1	252	[[Download>>attach:ChuckHillTemplates.tgz]]
44.1	253
	254	This is the default template with some useful (to me) changes:
	255
	256	* individual properties can be toggled open and closed
	257	* non-class hidden by default
	258	* less blank vertical space
	259	* column name moved into details
	260
	261	----
	262
50.1	263	[[image:attach:ChuckHillTemplate.png]]