yard 0.9.29 → 0.9.30

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of yard might be problematic. Click here for more details.

Files changed (152) hide show
  1. checksums.yaml +4 -4
  2. data/docs/CodeObjects.md +115 -0
  3. data/docs/GettingStarted.md +679 -0
  4. data/docs/Handlers.md +152 -0
  5. data/docs/Overview.md +61 -0
  6. data/docs/Parser.md +191 -0
  7. data/docs/Tags.md +283 -0
  8. data/docs/TagsArch.md +123 -0
  9. data/docs/Templates.md +496 -0
  10. data/docs/WhatsNew.md +1245 -0
  11. data/docs/images/code-objects-class-diagram.png +0 -0
  12. data/docs/images/handlers-class-diagram.png +0 -0
  13. data/docs/images/overview-class-diagram.png +0 -0
  14. data/docs/images/parser-class-diagram.png +0 -0
  15. data/docs/images/tags-class-diagram.png +0 -0
  16. data/docs/templates/default/fulldoc/html/full_list_tag.erb +9 -0
  17. data/docs/templates/default/fulldoc/html/setup.rb +6 -0
  18. data/docs/templates/default/layout/html/setup.rb +9 -0
  19. data/docs/templates/default/layout/html/tag_list.erb +11 -0
  20. data/docs/templates/default/yard_tags/html/list.erb +18 -0
  21. data/docs/templates/default/yard_tags/html/setup.rb +26 -0
  22. data/docs/templates/plugin.rb +70 -0
  23. data/lib/yard/version.rb +1 -1
  24. data/po/ja.po +31108 -0
  25. data/templates/default/class/dot/setup.rb +7 -0
  26. data/templates/default/class/dot/superklass.erb +3 -0
  27. data/templates/default/class/html/constructor_details.erb +8 -0
  28. data/templates/default/class/html/setup.rb +2 -0
  29. data/templates/default/class/html/subclasses.erb +4 -0
  30. data/templates/default/class/setup.rb +36 -0
  31. data/templates/default/class/text/setup.rb +12 -0
  32. data/templates/default/class/text/subclasses.erb +5 -0
  33. data/templates/default/constant/text/header.erb +11 -0
  34. data/templates/default/constant/text/setup.rb +4 -0
  35. data/templates/default/docstring/html/abstract.erb +4 -0
  36. data/templates/default/docstring/html/deprecated.erb +1 -0
  37. data/templates/default/docstring/html/index.erb +5 -0
  38. data/templates/default/docstring/html/note.erb +6 -0
  39. data/templates/default/docstring/html/private.erb +4 -0
  40. data/templates/default/docstring/html/returns_void.erb +1 -0
  41. data/templates/default/docstring/html/text.erb +1 -0
  42. data/templates/default/docstring/html/todo.erb +6 -0
  43. data/templates/default/docstring/setup.rb +52 -0
  44. data/templates/default/docstring/text/abstract.erb +2 -0
  45. data/templates/default/docstring/text/deprecated.erb +2 -0
  46. data/templates/default/docstring/text/index.erb +2 -0
  47. data/templates/default/docstring/text/note.erb +4 -0
  48. data/templates/default/docstring/text/private.erb +2 -0
  49. data/templates/default/docstring/text/returns_void.erb +1 -0
  50. data/templates/default/docstring/text/text.erb +1 -0
  51. data/templates/default/docstring/text/todo.erb +4 -0
  52. data/templates/default/fulldoc/html/css/common.css +1 -0
  53. data/templates/default/fulldoc/html/css/full_list.css +58 -0
  54. data/templates/default/fulldoc/html/css/style.css +497 -0
  55. data/templates/default/fulldoc/html/frames.erb +17 -0
  56. data/templates/default/fulldoc/html/full_list.erb +37 -0
  57. data/templates/default/fulldoc/html/full_list_class.erb +2 -0
  58. data/templates/default/fulldoc/html/full_list_file.erb +7 -0
  59. data/templates/default/fulldoc/html/full_list_method.erb +10 -0
  60. data/templates/default/fulldoc/html/js/app.js +314 -0
  61. data/templates/default/fulldoc/html/js/full_list.js +216 -0
  62. data/templates/default/fulldoc/html/js/jquery.js +4 -0
  63. data/templates/default/fulldoc/html/setup.rb +241 -0
  64. data/templates/default/layout/dot/header.erb +6 -0
  65. data/templates/default/layout/dot/setup.rb +15 -0
  66. data/templates/default/layout/html/breadcrumb.erb +11 -0
  67. data/templates/default/layout/html/files.erb +11 -0
  68. data/templates/default/layout/html/footer.erb +5 -0
  69. data/templates/default/layout/html/headers.erb +15 -0
  70. data/templates/default/layout/html/index.erb +2 -0
  71. data/templates/default/layout/html/layout.erb +24 -0
  72. data/templates/default/layout/html/listing.erb +4 -0
  73. data/templates/default/layout/html/objects.erb +32 -0
  74. data/templates/default/layout/html/script_setup.erb +4 -0
  75. data/templates/default/layout/html/search.erb +13 -0
  76. data/templates/default/layout/html/setup.rb +89 -0
  77. data/templates/default/method/html/header.erb +17 -0
  78. data/templates/default/method/setup.rb +4 -0
  79. data/templates/default/method/text/header.erb +1 -0
  80. data/templates/default/method_details/html/header.erb +3 -0
  81. data/templates/default/method_details/html/method_signature.erb +25 -0
  82. data/templates/default/method_details/html/source.erb +10 -0
  83. data/templates/default/method_details/setup.rb +11 -0
  84. data/templates/default/method_details/text/header.erb +10 -0
  85. data/templates/default/method_details/text/method_signature.erb +12 -0
  86. data/templates/default/method_details/text/setup.rb +11 -0
  87. data/templates/default/module/dot/child.erb +1 -0
  88. data/templates/default/module/dot/dependencies.erb +3 -0
  89. data/templates/default/module/dot/header.erb +6 -0
  90. data/templates/default/module/dot/info.erb +14 -0
  91. data/templates/default/module/dot/setup.rb +15 -0
  92. data/templates/default/module/html/attribute_details.erb +10 -0
  93. data/templates/default/module/html/attribute_summary.erb +8 -0
  94. data/templates/default/module/html/box_info.erb +43 -0
  95. data/templates/default/module/html/children.erb +8 -0
  96. data/templates/default/module/html/constant_summary.erb +17 -0
  97. data/templates/default/module/html/defines.erb +3 -0
  98. data/templates/default/module/html/header.erb +5 -0
  99. data/templates/default/module/html/inherited_attributes.erb +14 -0
  100. data/templates/default/module/html/inherited_constants.erb +8 -0
  101. data/templates/default/module/html/inherited_methods.erb +19 -0
  102. data/templates/default/module/html/item_summary.erb +40 -0
  103. data/templates/default/module/html/method_details_list.erb +9 -0
  104. data/templates/default/module/html/method_summary.erb +14 -0
  105. data/templates/default/module/html/methodmissing.erb +12 -0
  106. data/templates/default/module/html/pre_docstring.erb +1 -0
  107. data/templates/default/module/setup.rb +167 -0
  108. data/templates/default/module/text/children.erb +10 -0
  109. data/templates/default/module/text/class_meths_list.erb +8 -0
  110. data/templates/default/module/text/extends.erb +8 -0
  111. data/templates/default/module/text/header.erb +7 -0
  112. data/templates/default/module/text/includes.erb +8 -0
  113. data/templates/default/module/text/instance_meths_list.erb +8 -0
  114. data/templates/default/module/text/setup.rb +13 -0
  115. data/templates/default/onefile/html/files.erb +5 -0
  116. data/templates/default/onefile/html/headers.erb +6 -0
  117. data/templates/default/onefile/html/layout.erb +17 -0
  118. data/templates/default/onefile/html/readme.erb +3 -0
  119. data/templates/default/onefile/html/setup.rb +62 -0
  120. data/templates/default/root/dot/child.erb +3 -0
  121. data/templates/default/root/dot/setup.rb +6 -0
  122. data/templates/default/root/html/setup.rb +2 -0
  123. data/templates/default/tags/html/example.erb +11 -0
  124. data/templates/default/tags/html/index.erb +3 -0
  125. data/templates/default/tags/html/option.erb +24 -0
  126. data/templates/default/tags/html/overload.erb +14 -0
  127. data/templates/default/tags/html/see.erb +8 -0
  128. data/templates/default/tags/html/tag.erb +20 -0
  129. data/templates/default/tags/setup.rb +57 -0
  130. data/templates/default/tags/text/example.erb +12 -0
  131. data/templates/default/tags/text/index.erb +1 -0
  132. data/templates/default/tags/text/option.erb +20 -0
  133. data/templates/default/tags/text/overload.erb +19 -0
  134. data/templates/default/tags/text/see.erb +11 -0
  135. data/templates/default/tags/text/tag.erb +13 -0
  136. data/templates/guide/class/html/setup.rb +2 -0
  137. data/templates/guide/docstring/html/setup.rb +2 -0
  138. data/templates/guide/fulldoc/html/css/style.css +108 -0
  139. data/templates/guide/fulldoc/html/js/app.js +33 -0
  140. data/templates/guide/fulldoc/html/setup.rb +74 -0
  141. data/templates/guide/layout/html/layout.erb +81 -0
  142. data/templates/guide/layout/html/setup.rb +25 -0
  143. data/templates/guide/method/html/header.erb +18 -0
  144. data/templates/guide/method/html/setup.rb +22 -0
  145. data/templates/guide/module/html/header.erb +7 -0
  146. data/templates/guide/module/html/method_list.erb +5 -0
  147. data/templates/guide/module/html/setup.rb +27 -0
  148. data/templates/guide/onefile/html/files.erb +4 -0
  149. data/templates/guide/onefile/html/setup.rb +6 -0
  150. data/templates/guide/onefile/html/toc.erb +3 -0
  151. data/templates/guide/tags/html/setup.rb +9 -0
  152. metadata +151 -2
data/docs/Templates.md ADDED
@@ -0,0 +1,496 @@
1
+ # @title Templates Architecture
2
+
3
+ # Templates Architecture
4
+
5
+ Templates are the main component in the output rendering process of YARD,
6
+ which is invoked when conventional HTML/text output needs to be rendered
7
+ for a set of code objects.
8
+
9
+ ## Design Goals
10
+
11
+ The general design attempts to be as abstracted from actual content and templates
12
+ as possible. Unlike RDoc which uses one file to describe the entire template,
13
+ YARD splits up the rendering of code objects into small components, allowing
14
+ template modification for smaller subsets of a full template without having to
15
+ duplicate the entire template itself. This is necessary because of YARD's support
16
+ for plugins. YARD is designed for extensibility by external plugins, and because
17
+ of this, no one plugin can be responsible for the entire template because no
18
+ one plugin knows about the other plugins being used. For instance, if an RSpec
19
+ plugin was added to support and document specifications in class templates,
20
+ this information would need to be transparently added to the template to work
21
+ in conjunction with any other plugin that performed similar template modifications.
22
+ The design goals can be summarized as follows:
23
+
24
+ 1. Output should be able to be rendered for any arbitrary format with little
25
+ modification to YARD's source code. The addition of extra templates should
26
+ be sufficient.
27
+ 2. The output rendered for an object should independently rendered data
28
+ from arbitrary sources. These independent components are called "sections".
29
+ 3. Sections should be able to be inserted into any object without affecting
30
+ any existing sections in the document. This allows for easy modification
31
+ of templates by plugins.
32
+
33
+ ## Templates
34
+
35
+ Template modules are the objects used to orchestrate the design goals listed
36
+ above. Specifically, they organize the sections and render the template contents
37
+ depending on the format.
38
+
39
+ ## Engine
40
+
41
+ The Engine class orchestrates the creation and rendering of Template modules and
42
+ handles serialization or specific rendering scenarios (like HTML). To create
43
+ a template, use the {YARD::Templates::Engine.template template} method. The two most
44
+ common methods used to initiate output are the {YARD::Templates::Engine.render render}
45
+ and {YARD::Templates::Engine.generate generate} methods which generate and
46
+ optionally serialize output to a file. The latter, `#generate`, is used
47
+ specially to generate HTML documentation and copy over assets that may be
48
+ needed. For instance, an object may be rendered with:
49
+
50
+ YARD::Templates::Engine.render(:object => myobject)
51
+
52
+ A set of objects may be rendered into HTML documentation by using:
53
+
54
+ # all_objects is an array of module and class objects
55
+ # options includes a :serializer key to copy output to the file system
56
+ YARD::Templates::Engine.generate(all_objects, options)
57
+
58
+ Note that these methods should not be called directly. The {YARD::CodeObjects::Base}
59
+ class has a {YARD::CodeObjects::Base#format #format} helper method to render an
60
+ object. For instance, the above render example is equivalent to the simple
61
+ call `myobject.format`. The `generate` method is a special kind of render
62
+ and is called from the {YARD::CLI::Yardoc} command line utility.
63
+
64
+ ## Template Options
65
+
66
+ A template keeps state when it is rendering output. This state is kept in
67
+ an options hash which is initially passed to it during instantiation. Some
68
+ default options set the template style (`:template`), the output format (`:format`),
69
+ and the serializer to use (`:serializer`). This options hash is modifiable
70
+ from all methods seen above. For example, initializing a template to output as
71
+ HTML instead of text can be done as follows:
72
+
73
+ myobject.format(:format => :html)
74
+
75
+ ## Serializer
76
+
77
+ This class abstracts the logic involved in deciding how to serialize data to
78
+ the expected endpoint. For instance, there is both a {YARD::Serializers::StdoutSerializer StdoutSerializer}
79
+ and {YARD::Serializers::FileSystemSerializer FileSystemSerializer} class for
80
+ outputting to console or to a file respectively. When endpoints with locations
81
+ are used (like files or URLs), the serializer implements the {YARD::Serializers::Base#serialized_path #serialized_path}
82
+ method. This allows the translation from a code object to its path at the endpoint,
83
+ which enables inter-document linking.
84
+
85
+ Rendered objects are automatically serialized using the object if present,
86
+ otherwise the rendered object is returned as a string to its parent. Nested
87
+ Templates automatically set the serializer to nil so that they return
88
+ as a String to their parent.
89
+
90
+ ## Creating a Template
91
+
92
+ Templates are represented by a directory inside the {YARD::Templates::Engine.template_paths}
93
+ on disk. A standard template directory looks like the following tree:
94
+
95
+ (Assuming templates/ is a template path)
96
+ templates
97
+ `-- default
98
+ |-- class
99
+ | |-- dot
100
+ | | |-- setup.rb
101
+ | | `-- superklass.erb
102
+ | |-- html
103
+ | | |-- constructor_details.erb
104
+ | | |-- setup.rb
105
+ | | `-- subclasses.erb
106
+ | |-- setup.rb
107
+ | `-- text
108
+ | |-- setup.rb
109
+ | `-- subclasses.erb
110
+ |-- docstring
111
+ | |-- html
112
+ | | |-- abstract.erb
113
+ | | |-- deprecated.erb
114
+ | | |-- index.erb
115
+ | | `-- text.erb
116
+ | |-- setup.rb
117
+ | `-- text
118
+ | |-- abstract.erb
119
+ | |-- deprecated.erb
120
+ | |-- index.erb
121
+ | `-- text.erb
122
+
123
+ The path `default` refers to the template style (:template key in options hash)
124
+ and the directories at the next level (such as `class`) refer to template
125
+ `:type` (options hash key) for a template. The next directory refers to the
126
+ output format being used defined by the `:format` template option.
127
+
128
+ As we saw in the above example, the format option can be set to `:html`, which
129
+ would use the `html/` directory instead of `text/`. Finally, the individual .erb
130
+ files are the sections that make up the template.
131
+
132
+ Note that the subdirectory `html/` is also its own "template" that inherits
133
+ from the parent directory. We will see more on this later.
134
+
135
+ ## setup.rb
136
+
137
+ Every template should have at least one `setup.rb` file that defines the
138
+ {YARD::Templates::Template#init #init} method to set the
139
+ {YARD::Templates::Template#sections #sections} used by the template. If
140
+ a setup.rb is not defined in the template itself, there should be a template
141
+ that is inherited (via parent directory or explicitly) that sets the sections
142
+ on a newly created template.
143
+
144
+ A standard setup.rb file looks like:
145
+
146
+ def init
147
+ sections :section1, :section2, :section3
148
+ end
149
+
150
+ ## Sections
151
+
152
+ Sections are smaller components that correlate to template
153
+ fragments. Practically speaking, a section can either be a template fragment
154
+ (a conventional .erb file or other supported templating language), a method
155
+ (which returns a String) or another {YARD::Templates::Template} (which in turn has its own
156
+ list of sections).
157
+
158
+ ## Nested Sections
159
+
160
+ Sections often require the ability to encapsulate a set of sub-sections in markup
161
+ (HTML, for instance). Rather than use heavier Template subclass objects, a more
162
+ lightweight solution is to nest a set of sub-sections as a list that follows
163
+ a section, for example:
164
+
165
+ def init
166
+ sections :header, [:section_a, :section_b]
167
+ end
168
+
169
+ The above example nests `section_a` and `section_b` within the `header` section.
170
+ Practically speaking, these sections can be placed in the result by `yield`ing
171
+ to them. A sample header.erb template might contain:
172
+
173
+ <h2>Header</h2>
174
+ <div id="contents">
175
+ <%= yieldall %>
176
+ </div>
177
+
178
+ This template code would place the output of `section_a` and `section_b` within
179
+ the above div element. Using `yieldall`, we can also change the object that is being
180
+ rendered. For example, we may want to yield the first method of the class.
181
+ We can do this like so:
182
+
183
+ <h2>First method</h2>
184
+ <%= yieldall :object => object.meths.first %>
185
+
186
+ This would run the nested sections for the method object instead of the class.
187
+
188
+ Note that `yieldall` yields to all subsections, whereas `yield` will yield
189
+ to each individually (in order) until there are no more left to yield to.
190
+ In the vast majority of cases, you'd want to use `yieldall`, since `yield`
191
+ makes it hard for users to override your template.
192
+
193
+ ## Inheriting Templates
194
+
195
+ Parent directory templates are automatically inherited (or mixed in, to be
196
+ more accurate) by the current template. This means that the 'default/class/html'
197
+ template automatically inherits from 'default/class'. This also means that anything
198
+ defined in 'default/class/setup.rb' can be overridden by 'default/class/html/setup.rb'.
199
+
200
+ Since the Template module is a module, and not a class, they can be mixed in
201
+ explicitly (via include/extend) from other templates, which allows templates
202
+ to share erb files or helper logic. The 'default/class' template explicitly
203
+ mixes in the 'default/module' template, since it uses much of the same sections.
204
+ This is done with the helper {YARD::Templates::Template::ClassMethods#T T} method, which
205
+ is simply a shorthand for {YARD::Templates::Engine.template Engine.template}.
206
+ It can then override (using standard inheritance) the sections from the module
207
+ template and insert sections pertaining to classes. This is one of the design
208
+ goals described above.
209
+
210
+ For instance, the first line in `default/class/html/setup.rb` is:
211
+
212
+ include T('default/module/html')
213
+
214
+ This includes the 'default/module/html', which means it also includes 'default/module'
215
+ by extension. This allows class to make use of any of module's erb files.
216
+
217
+ ## Inserting and Traversing Sections
218
+
219
+ The ability to insert sections was mentioned above. The class template, for
220
+ instance, will modify the #init method to insert class specific sections:
221
+
222
+ def init
223
+ super
224
+ sections.place(:subclasses).before(:children)
225
+ sections.delete(:children)
226
+ sections.place([:constructor_details, [T('method_details')]]).before(:methodmissing)
227
+ end
228
+
229
+ Observe how sections has been modified after the super method was called (the
230
+ super method would have been defined in `default/module/setup.rb`). The
231
+ `sections` object is of the {YARD::Templates::Section} class and allows sections to be inserted
232
+ before or after another section using {Array#place} by it's given name rather
233
+ than index. This allows the overriding of templates in a way that does not
234
+ depend on where the section is located (since it may have been overridden by
235
+ another module).
236
+
237
+ You can also use `sections[:name]` to find the first child section named `:name`.
238
+ For instance, with the following sections declaration:
239
+
240
+ sections :a, [:b, :c, [:d]]
241
+
242
+ You can get to the :d section with:
243
+
244
+ sections[:a][:c][:d]
245
+
246
+ You can use this to insert a section inside a nested set without using indexed
247
+ access. The following command would result in `[:a, [:b, :c, [:d, :e]]]`:
248
+
249
+ sections[:a][:c].place(:e).after(:d)
250
+
251
+ There are also two methods, {Insertion#before_any} and {Insertion#after_any},
252
+ which allow you to insert sections before or after the first matching section name
253
+ recursively. The above example could simply be rewritten as:
254
+
255
+ sections.place(:e).after_any(:d)
256
+
257
+ ## Overriding Templates by Registering a Template Path
258
+
259
+ Inheriting templates explicitly is useful when creating a customized template
260
+ that wants to take advantage of code re-use. However, most users who want
261
+ to customize YARD templates will want to override existing behaviour without
262
+ creating a template from scratch.
263
+
264
+ YARD solves this problem by allowing other template paths to be registered.
265
+ Because template modules are represented by a relative path such as 'default/class',
266
+ they can be found within any of the registered template paths. A new template
267
+ path is registered as:
268
+
269
+ YARD::Templates::Engine.register_template_path '/path/to/mytemplates'
270
+
271
+ At this point, any time the 'default/class' template is loaded, the template
272
+ will first be looked for inside the newly registered template path. If found,
273
+ it will be used as the template module, with the modules from the other
274
+ template paths implicitly mixed in.
275
+
276
+ Therefore, by using the same directory structure as a builtin YARD template,
277
+ a user can customize or override individual templates as if the old ones were
278
+ inherited. A real world example would further modify the 'default/class' template
279
+ seen above by creating such a path in our '/path/to/mytemplates' custom template
280
+ path:
281
+
282
+ /path/to/mytemplates/:
283
+ |-- class
284
+ | |-- html
285
+ | | |-- customsection.erb
286
+ | |-- setup.rb
287
+
288
+ The `setup.rb` file would look like:
289
+
290
+ def init
291
+ super
292
+ sections.push :customsection
293
+ end
294
+
295
+ Now, when a class object is formatted as HTML, our customsection.erb will be
296
+ appended to the rendered data.
297
+
298
+
299
+ ### Overriding Stylesheets and Javascripts
300
+
301
+ Template authors can override existing stylesheets and javascripts by creating
302
+ a file with the same name as existing files within the `fulldoc` template. The
303
+ documentation output will utilize the new replacement file.
304
+
305
+ YARD's `fulldoc` template defines three stylesheets:
306
+
307
+ /yard/templates/default/:
308
+ |-- fulldoc
309
+ | |-- html
310
+ | | |-- css
311
+ | | | |-- common.css
312
+ | | | |-- full_list.css
313
+ | | | |-- style.css
314
+
315
+ The `style.css` is the primary stylesheet for the HTML output.
316
+
317
+ The `full_list.css` is an additional stylesheet loaded specifically for the
318
+ search field menus (i.e. class list, method list, and file list).
319
+
320
+ The `common.css` is an empty css file that an template author can easily override
321
+ to provide custom styles for their plugin. However, if a user installs multiple
322
+ plugins that utilize this same file to deliver styles, it is possible that they
323
+ will be overridden.
324
+
325
+ YARD's `fulldoc` template defines three javascript files:
326
+
327
+ /yard/templates/default/:
328
+ |-- fulldoc
329
+ | |-- html
330
+ | | |-- js
331
+ | | | |-- app.js
332
+ | | | |-- full_list.js
333
+ | | | |-- jquery.js
334
+
335
+ The `app.js` is the primary javascript file for the HTML output.
336
+
337
+ The `full_list.js` defines additional javascript loaded specifically for the
338
+ search field menus (i.e. class list, method list, and file list).
339
+
340
+ The `jquery.js` is copy of the jquery javascript library.
341
+
342
+ ### Adding a Custom Stylesheet or Javascript
343
+
344
+ To load additional stylesheets and javascripts with every page (except the search
345
+ field menus) generated from the base `layout` template:
346
+
347
+ 1. Define your own custom stylesheet and/or javascript file
348
+ (default/ is the default template name inside of the /template root directory):
349
+
350
+ /template/default/:
351
+ |-- fulldoc
352
+ | |-- html
353
+ | | |-- css
354
+ | | | |-- custom.css
355
+ | | |-- js
356
+ | | | |-- custom.js
357
+
358
+ 2. Create a `setup.rb` in the `layout` template directory and override the methods
359
+ `stylesheets` and `javascripts`. The path to the template would be:
360
+
361
+ /template/default/:
362
+ |-- layout
363
+ | |-- html
364
+ | | |-- setup.rb
365
+
366
+ And the code would look like:
367
+
368
+ def stylesheets
369
+ # Load the existing stylesheets while appending the custom one
370
+ super + %w(css/custom.css)
371
+ end
372
+
373
+ def javascripts
374
+ # Load the existing javascripts while appending the custom one
375
+ super + %w(js/custom.js)
376
+ end
377
+
378
+
379
+ To load additional stylesheets and javascripts for the search menus loaded from
380
+ the `fulldoc` template:
381
+
382
+ 1. Define your own custom stylesheet and/or javascript file.
383
+
384
+ /path/to/mytemplates/:
385
+ |-- fulldoc
386
+ | |-- html
387
+ | | |-- css
388
+ | | | |-- custom_full_menu.css
389
+ | | |-- js
390
+ | | | |-- custom_full_menu.js
391
+
392
+
393
+ 3. Override the methods `stylesheets_full_list` and `javascripts_full_list`
394
+ in the `setup.rb` file inside fulldoc/html.
395
+
396
+ def stylesheets_full_list
397
+ # Load the existing stylesheets while appending the custom one
398
+ super + %w(css/custom.css)
399
+ end
400
+
401
+ def javascripts_full_list
402
+ # Load the existing javascripts while appending the custom one
403
+ super + %w(js/custom.js)
404
+ end
405
+
406
+ ### Overriding Search Menus
407
+
408
+ By default YARD's `fulldoc` template generates three search fields:
409
+
410
+ * Class List
411
+ * Method List
412
+ * File List
413
+
414
+ Their contents are rendered in methods within the `fulldoc` template:
415
+
416
+ * `generate_class_list`
417
+ * `generate_method_list`
418
+ * `generate_file_list`
419
+
420
+ To override these lists you will need to:
421
+
422
+ 1. Create a `setup.rb` in the `fulldoc` template directory and override the
423
+ particular method.
424
+
425
+ /path/to/mytemplates/:
426
+ |-- fulldoc
427
+ | |-- html
428
+ | | |-- setup.rb
429
+
430
+ def generate_method_list
431
+ @items = prune_method_listing(Registry.all(:method), false)
432
+ @items = @items.reject {|m| m.name.to_s =~ /=$/ && m.is_attribute? }
433
+
434
+ # Here we changed the functionality to reverse the order of displayed methods
435
+ @items = @items.sort_by {|m| m.name.to_s }.reverse
436
+ @list_title = "Method List"
437
+ @list_type = "methods"
438
+ asset('method_list.html', erb(:full_list))
439
+ end
440
+
441
+ ### Adding Additional Search Menus
442
+
443
+ By default YARD's `fulldoc` template generates three search fields:
444
+
445
+ * Class List
446
+ * Method List
447
+ * File List
448
+
449
+ These are defined in the `layout` template method `menu_lists` and pulled into
450
+ the `fulldoc` template through a similarly named method.
451
+
452
+ To load an additional menu item:
453
+
454
+
455
+ 1. Create a `setup.rb` in the `layout` template directory and override the methods
456
+ `menu_lists`. The `type` informs the search field the name of the file.
457
+ The `title` is the name that appears above the section when viewed in frames.
458
+ The `search_title` is the name that appears in the search field tab on the page.
459
+
460
+
461
+ /path/to/mytemplates/:
462
+ |-- layout
463
+ | |-- html
464
+ | | |-- setup.rb
465
+
466
+ def menu_lists
467
+ # Load the existing menus
468
+ super + [ { :type => 'feature', :title => 'Features', :search_title => 'Feature List' } ]
469
+ end
470
+
471
+ 2. Create a `setup.rb` in the `fulldoc` template directory and create a method
472
+ to generate a menu for the specified `type`.
473
+ The method `generate_assets` will look for a function with a signature prefixed
474
+ with `generate`, the type value specified, and the suffix `list`. Within that
475
+ method you can configure and load the specific objects you wish to display.
476
+
477
+ /path/to/mytemplates/:
478
+ |-- fulldoc
479
+ | |-- html
480
+ | | |-- setup.rb
481
+
482
+ def generate_feature_list
483
+
484
+ # load all the features from the Registry
485
+ @items = Registry.all(:feature)
486
+ @list_title = "Feature List"
487
+ @list_type = "feature"
488
+
489
+ # optional: the specified stylesheet class
490
+ # when not specified it will default to the value of @list_type
491
+ @list_class = "class"
492
+
493
+ # Generate the full list html file with named feature_list.html
494
+ # @note this file must be match the name of the type
495
+ asset('feature_list.html', erb(:full_list))
496
+ end