Skip to Content

Changes for page EOModelDoc

Last modified by Theodore Petrosky on 2012/02/11 13:36
From version 51.1
edited by Pascal Robert
on 2012/02/11 13:36
Change comment: Migrated to Confluence 5.3
To version 49.1
edited by Pascal Robert
on 2012/02/11 13:36
Change comment: There is no comment for this version

Summary

Details

Page properties
Parent
... ... @@ -1,1 +1,0 @@
1 -Home
Content
... ... @@ -1,73 +1,49 @@
1 1  == Contents ==
2 2  
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"]]
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 10  
11 11  == Overview ==
12 12  
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.
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.
14 14  
15 -On the WOLips side, from version 3.3.x, [[Entity Modeler>>doc:documentation.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>>documentation: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.
16 16  
17 17  == Future Plans ==
18 18  
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.//
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.//
20 20  
21 21  == Download and Example Output ==
22 22  
23 -[[Download EOModelDoc jar>>url:http://wocommunity.org/documents/tools/eomodeldoc.jar||shape="rect"]]
23 +[[Download EOModelDoc jar>>http://wocommunity.org/documents/tools/eomodeldoc.jar]]
24 24  
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"]]
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>>http://webobjects.mdimension.com/wolips/support/eomodeldoc_example/]]
27 27  
28 28  == Usage ==
29 29  
30 30  The command line syntax of for EOModelDoc:
31 31  
32 -{{code language="none"}}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{{/code}}
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##
33 33  
34 -|=(((
35 -Parameter
36 -)))|=(((
37 -Usage / Function
38 -)))
39 -|(((
40 -output
41 -)))|(((
42 -Path to the directory where the output HTML files will be written.
43 -)))
44 -|(((
45 -model
46 -)))|(((
47 -Path to one model to generate documentation for. This parameter can be used multiple times, once for each model.
48 -)))
49 -|(((
50 -modelgroup
51 -)))|(((
52 -The path to an Eclipse or IDEA project. All models listed in the project will be documented. This defaults to the current working directory.
53 -)))
54 -|(((
55 -templates
56 -)))|(((
57 -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.
58 -)))
59 -|(((
60 -entityURLTemplate
61 -)))|(((
62 -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.
63 -)))
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.
64 64  
65 65  === Notes ===
66 66  
67 -* Only {{code language="none"}}-output{{/code}} is required
68 -* 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)
69 -* 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.
70 -* 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}}
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/]]##
71 71  
72 72  === Usage Examples ===
73 73  
... ... @@ -97,11 +97,12 @@
97 97  
98 98  == Running from Ant ==
99 99  
100 -**Note**: do not put this jar on your classpath! Chaos and Other Bad Things may ensue.
76 +**Note**: do not put this jar on your classpath Chaos and Other Bad Things may ensue.
101 101  
102 -There is no Ant task (yet) for EOModelDoc. You can run it with an {{code language="none"}}java{{/code}} task following this pattern:
78 +There is no Ant task (yet) for EOModelDoc. You can run it with an ##java## task following this pattern:
103 103  
104 -{{code 0="xml"}}
80 +{{code value="xml"}}
81 +
105 105  <java jar="/path/to/eomodeldoc.jar"
106 106   fork="true"
107 107   maxmemory="256m">
... ... @@ -114,10 +114,11 @@
114 114   <arg value="-entityURLTemplate" />
115 115   <arg value="http://whatever?$${entity.classNamePath}.html" />
116 116  </java>
117 -{{/code}}
118 118  
119 -{{code 0="xml"}}
95 +{{/code}}
120 120  
97 +{{code value="xml"}}
98 +
121 121  <java jar="/path/to/eomodeldoc.jar"
122 122   fork="true"
123 123   maxmemory="256m">
... ... @@ -139,7 +139,7 @@
139 139  
140 140  If you include this in the build.xml file in the project, it can be as simple as:
141 141  
142 -{{code 0="xml"}}
120 +{{code value="xml"}}
143 143  
144 144  <java jar="/path/to/eomodeldoc.jar"
145 145   fork="true"
... ... @@ -154,7 +154,7 @@
154 154  
155 155  == Template Files ==
156 156  
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:
135 +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:
158 158  
159 159  {{code}}
160 160  
... ... @@ -162,94 +162,45 @@
162 162  
163 163  {{/code}}
164 164  
165 -See the [[EOGenerator template documentation>>doc:EOGenerator Templates and Additions]] 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.
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.
166 166  
167 167  The templates and their function are:
168 168  
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 -
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. |
230 230  Some pictures will illustrate this:
231 231  
232 232  ----
233 233  
234 -[[image:attach:EOModelDocTemplates1.png]]
163 +[[image:EOModelDocTemplates1.png||width="800"]]
235 235  
236 236  ----
237 237  
238 -[[image:attach:EOModelDocTemplates2.png]]
167 +[[image:EOModelDocTemplates2.png||width="800"]]
239 239  
240 240  ----
241 241  
242 -[[image:attach:EOModelDocTemplates3.png]]
171 +[[image:EOModelDocTemplates3.png||width="800"]]
243 243  
244 244  ----
245 245  
246 246  == Alternate Templates ==
247 247  
248 -Have some interesting templates to share? Add them as attachements and link them here.
177 +Have some interesting templates to share? Add them as attachements and link them here.
249 249  
250 250  === Template Mark I from Chuck ===
251 251  
252 -[[Download>>attach:ChuckHillTemplates.tgz]]
181 +[[Download>>^ChuckHillTemplates.tgz]]
253 253  
254 254  This is the default template with some useful (to me) changes:
255 255  
... ... @@ -260,4 +260,4 @@
260 260  
261 261  ----
262 262  
263 -[[image:attach:ChuckHillTemplate.png]]
192 +[[image:ChuckHillTemplate.png]]
ChuckHillTemplate.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.XWikiGuest
Size
... ... @@ -1,1 +1,0 @@
1 -73.7 KB
Content
ChuckHillTemplates.tgz
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.XWikiGuest
Size
... ... @@ -1,1 +1,0 @@
1 -3.0 KB
Content
EOModelDocTemplates1.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.XWikiGuest
Size
... ... @@ -1,1 +1,0 @@
1 -175.0 KB
Content
EOModelDocTemplates2.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.XWikiGuest
Size
... ... @@ -1,1 +1,0 @@
1 -142.7 KB
Content
EOModelDocTemplates3.png
Author
... ... @@ -1,1 +1,0 @@
1 -XWiki.XWikiGuest
Size
... ... @@ -1,1 +1,0 @@
1 -127.8 KB
Content