Changes for page EOModelDoc

Summary

• Page properties (2 modified, 0 added, 0 removed)

Details

Page properties

Author

...	...	@@ -1,1 +1,1 @@
1		-XWiki.chillatgvc
	1	+XWiki.pierce

Content

...	...	@@ -1,8 +1,18 @@
	1	+== Contents ==
	2	+
	3	+[[||anchor="Overview"]]
	4	+[[||anchor="Future Plans"]]
	5	+[[||anchor="Download and Example Output"]]
	6	+[[||anchor="Usage"]]
	7	+[[||anchor="Running from Ant"]]
	8	+[[||anchor="Template Files"]]
	9	+[[||anchor="Alternate Templates"]]
	10	+
1	1	== Overview ==
2	2
3		-EOModelDoc is a command line tool to generate HTML documentation of a set of EOModels. It is a replacement for [[EOReporter>>http://www.rubicode.com/Software/EOReporter/]] (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.
	13	+EOModelDoc is a command line tool to generate HTML documentation of a set of EOModels. It is a replacement for [[EOReporter>>http://www.rubicode.com/Software/EOReporter/]] (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.
4	4
5		-On the WOLips side, from version 3.3.x, [[Entity Modeler>>Using Entity Modeler]] 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.
	15	+On the WOLips side, from version 3.3.x, [[Entity Modeler>>Using Entity Modeler]] 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.
6	6
7	7	== Future Plans ==
8	8
...	...	@@ -10,24 +10,31 @@
10	10
11	11	== Download and Example Output ==
12	12
13		-[[Download EOModelDoc jar>>http://webobjects.mdimension.com/wolips/eomodeldoc.jar]]
	23	+[[Download EOModelDoc jar>>http://webobjects.mdimension.com/wolips/eomodeldoc-latest.jar]]
14	14
15		-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.
	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.
16	16	[[View Example Output>>http://webobjects.mdimension.com/wolips/eomodeldoc_example/]]
17	17
18	18	== Usage ==
19	19
20	20	The command line syntax of for EOModelDoc:
21		-
22		-##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:~/~/whatever?$entity.classNamePath}.html**##
23	23
24		-|=Parameter|=Usage / Function
25		-|output|Path to the directory where the output HTML files will be written.
26		-|model|Path to one model to generate documentation for. This parameter can be used multiple times, once for each model.
27		-|modelgroup|The path to an Eclipse or IDEA project. All models listed in the project will be documented. This defaults to the current working directory.
28		-|templates|Path to the directory where the Velocity templates are stored. See the [[||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.
29		-|entityURLTemplate|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.
	32	+##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##
30	30
	34	+|= Parameter |= Usage / Function
	35	+| output | Path to the directory where the output HTML files will be written.
	36	+| model | Path to one model to generate documentation for. This parameter can be used multiple times, once for each model.
	37	+| modelgroup | The path to an Eclipse or IDEA project. All models listed in the project will be documented. This defaults to the current working directory.
	38	+| templates | Path to the directory where the Velocity templates are stored. See the [[||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.
	39	+| entityURLTemplate | 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.
	40	+
	41	+=== Notes ===
	42	+
	43	+* Only ##output## is required
	44	+* Usually only one of ##modelGroup## or ##model## is used (i.e. not both at the same time)
	45	+* The ##templates## 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.
	46	+* For ##entityURLTemplate## the ##[[http://domain/path/to/JavaDocs/]]## the path to the index.html file that JavaDoc generates. It will be something like ##[[http://developer.apple.com/documentation/MacOSXServer/Reference/WO54_Reference/]]##. 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/]]##
	47	+
31	31	=== Usage Examples ===
32	32
33	33	Document one model:
...	...	@@ -34,16 +34,15 @@
34	34
35	35	{{code}}
36	36
37		-java -jar eomodeldoc.jar -model /path/to/model.eomodeld -output /tmp/eomodeldoc
	54	+java -jar /path/to/eomodeldoc.jar -model /path/to/model.eomodeld -output /tmp/eomodeldoc
38	38
39	39	{{/code}}
40	40
41		-
42		-Document all models based on the Eclipse or IDEA project definition:
	58	+Document all models based on the Eclipse or IDEA project definition:
43	43
44	44	{{code}}
45	45
46		-java -jar eomodeldoc.jar -modelgroup /path/to/project -output /tmp/eomodeldoc
	62	+java -jar /path/to/eomodeldoc.jar -modelgroup /path/to/project -output /tmp/eomodeldoc
47	47
48	48	{{/code}}
49	49
...	...	@@ -51,10 +51,69 @@
51	51
52	52	{{code}}
53	53
54		-java -jar eomodeldoc.jar -output /tmp/eomodeldoc
	70	+java -jar /path/to/eomodeldoc.jar -output /tmp/eomodeldoc
55	55
56	56	{{/code}}
57	57
	74	+== Running from Ant ==
	75	+
	76	+**Note**: do not put this jar on your classpath Chaos and Other Bad Things may ensue.
	77	+
	78	+There is no Ant task (yet) for EOModelDoc. You can run it with an ##java## task following this pattern:
	79	+
	80	+{{code value="xml"}}
	81	+
	82	+<java jar="/path/to/eomodeldoc.jar"
	83	+ fork="true"
	84	+ maxmemory="256m">
	85	+ <arg value="-output" />
	86	+ <arg value="/path/to/output/folder" />
	87	+ <arg value="-modelgroup" />
	88	+ <arg value="/path/to/working/dir" />
	89	+ <arg value="-templates" />
	90	+ <arg value="/path/to/templates" />
	91	+ <arg value="-entityURLTemplate" />
	92	+ <arg value="http://whatever?$${entity.classNamePath}.html" />
	93	+</java>
	94	+
	95	+{{/code}}
	96	+
	97	+{{code value="xml"}}
	98	+
	99	+<java jar="/path/to/eomodeldoc.jar"
	100	+ fork="true"
	101	+ maxmemory="256m">
	102	+ <arg value="-output" />
	103	+ <arg value="/path/to/output/folder" />
	104	+ <arg value="-model" />
	105	+ <arg value="/path/to/modelA.eomodeld" />
	106	+ <arg value="-model" />
	107	+ <arg value="/path/to/modelB.eomodeld" />
	108	+ <arg value="-model" />
	109	+ <arg value="/path/to/modelC.eomodeld" />
	110	+ <arg value="-templates" />
	111	+ <arg value="/path/to/templates" />
	112	+ <arg value="-entityURLTemplate" />
	113	+ <arg value="http://whatever?$${entity.classNamePath}.html" />
	114	+</java>
	115	+
	116	+{{/code}}
	117	+
	118	+If you include this in the build.xml file in the project, it can be as simple as:
	119	+
	120	+{{code value="xml"}}
	121	+
	122	+<java jar="/path/to/eomodeldoc.jar"
	123	+ fork="true"
	124	+ maxmemory="256m">
	125	+ <arg value="-output" />
	126	+ <arg value="Documentation" />
	127	+ <arg value="-modelgroup" />
	128	+ <arg value="." />
	129	+</java>
	130	+
	131	+{{/code}}
	132	+
58	58	== Template Files ==
59	59
60	60	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:
...	...	@@ -65,23 +65,22 @@
65	65
66	66	{{/code}}
67	67
68		-Only need to have the templates that are different from the jar?
	143	+See the [[EOGenerator template documentation>>EOGenerator Templates and Additions]] documentation for information on customizing these templates. The ##templates## 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.
69	69
70	70	The templates and their function are:
71	71
72		-|=Template Name|=Usage / Function
73		-|indexModels.html.vm|Left pane index of all models.
74		-|indexOverview.html.vm|Left pane index of the contents of all models (e.g. list of entities and stored procedures).
75		-|modelOverview.html.vm|Left pane index of the contents of one model (e.g. list of entities and stored procedures).
76		-|indexContent.html.vm|Main frame description of each model and contents of each model (e.g. list of entities and stored procedures).
77		-|modelContent.html.vm|Main frame contents of one model (list of entities and stored procedures).|
78		-|entityContent.html.vm|Main frame contents for one Entity
79		-|storedProcedureContent.html.vm|Main frame contents for one stored procedure.
80		-|index.html.vm|Top level index.html file defining frameset. You probably won't need to modify this.
81		-|prototype.js.vm|[[Prototype>>http://www.prototypejs.org/learn]] JavaScript file so that the generated documentation can use Ajax whizziness. You probably won't need to modify this.
82		-|eomodeldoc.css.vm|CSS file that controls what the generate output looks like.
83		-|eomodeldoc.js.vm|JavaScript file that cleans up the display. You probably won't need to modify this.
84		-
	147	+|= Template Name |= Usage / Function
	148	+| indexModels.html.vm | Left pane index of all models.
	149	+| indexOverview.html.vm | Left pane index of the contents of all models (e.g. list of entities and stored procedures).
	150	+| modelOverview.html.vm | Left pane index of the contents of one model (e.g. list of entities and stored procedures).
	151	+| indexContent.html.vm | Main frame description of each model and contents of each model (e.g. list of entities and stored procedures).
	152	+| modelContent.html.vm | Main frame contents of one model (list of entities and stored procedures).
	153	+| entityContent.html.vm | Main frame contents for one Entity
	154	+| storedProcedureContent.html.vm | Main frame contents for one stored procedure.
	155	+| index.html.vm | Top level index.html file defining frameset. You probably won't need to modify this.
	156	+| prototype.js.vm | [[Prototype>>http://www.prototypejs.org/learn]] JavaScript file so that the generated documentation can use Ajax whizziness. You probably won't need to modify this.
	157	+| eomodeldoc.css.vm | CSS file that controls what the generate output looks like.
	158	+| eomodeldoc.js.vm | JavaScript file that cleans up the display. You probably won't need to modify this. |
85	85	Some pictures will illustrate this:
86	86
87	87	----
...	...	@@ -95,8 +95,24 @@
95	95	----
96	96
97	97	[[image:EOModelDocTemplates3.png||width="800"]]
98		-
99	99
100	100	----
101	101
102		-== Running from Ant ==
	175	+== Alternate Templates ==
	176	+
	177	+Have some interesting templates to share? Add them as attachements and link them here.
	178	+
	179	+=== Template Mark I from Chuck ===
	180	+
	181	+[[Download>>^ChuckHillTemplates.tgz]]
	182	+
	183	+This is the default template with some useful (to me) changes:
	184	+
	185	+* individual properties can be toggled open and closed
	186	+* non-class hidden by default
	187	+* less blank vertical space
	188	+* column name moved into details
	189	+
	190	+----
	191	+
	192	+[[image:ChuckHillTemplate.png]]