1 # This file is part of NIT ( http://www.nitlanguage.org ).
3 # Licensed under the Apache License, Version 2.0 (the "License");
4 # you may not use this file except in compliance with the License.
5 # You may obtain a copy of the License at
7 # http://www.apache.org/licenses/LICENSE-2.0
9 # Unless required by applicable law or agreed to in writing, software
10 # distributed under the License is distributed on an "AS IS" BASIS,
11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 # See the License for the specific language governing permissions and
13 # limitations under the License.
15 # Base entities shared by all the nitdoc code.
20 import model
::model_collect
22 # The model of a Nitdoc documentation.
24 # `DocModel` contains the list of the `DocPage` to be generated.
26 # The model is populated through `DocPhase` to be constructed.
27 # It is a placeholder to share data between each phase.
30 # Model to generate the documentation for
33 # Main module of the sources behing documented
34 var mainmodule
: MModule
36 # Model filters to apply
37 var filter
: ModelFilter
39 # `DocPage` composing the documentation associated to their ids.
41 # This is where `DocPhase` store and access pages to produce documentation.
44 var pages
: Map[String, DocPage] = new HashMap[String, DocPage]
46 # Add a `page` to this documentation.
47 fun add_page
(page
: DocPage) do
48 if pages
.has_key
(page
.id
) then
49 print
"Warning: multiple page with the same id `{page.id}`"
55 # A documentation page abstraction.
57 # The page contains a link to the `root` of the `DocComposite` that compose the
63 # The `id` is used as name for the generated file corresponding to the page
65 # Because multiple pages can be generated in the same directory it should be
68 # The `id` can also be used to establish links between pages (HTML links,
69 # HTML anchors, vim links, etc.).
70 var id
: String is writable
73 var title
: String is writable
75 # Root element of the page.
77 # `DocPhase` access the structure of the page from the `DocRoot`.
78 var root
= new DocRoot
80 redef fun to_s
do return title
82 # Pretty prints the content of this page.
83 fun pretty_print
: Writable do
84 var res
= new Template
85 res
.addn
"{class_name} {title}"
86 for child
in root
.children
do
87 child
.pretty_print_in
(res
)
93 # `DocPage` elements that can be nested in another.
95 # `DocComposite` is an abstraction for everything that go in a `DocPage` like
96 # sections, articles, images, lists, graphs...
98 # It provides base services for nesting mechanisms following the
99 # *Composite pattern*.
100 # The composed structure is a tree from a `DocRoot` that can be manipulated
102 abstract class DocComposite
105 var parent
: nullable DocComposite = null is writable
109 # The `id` is used as name for the generated element (if any).
110 # Because multiple elements can be generated in the same container
113 # The `id` can also be used to establish links between elements
114 # (HTML links, HTML anchors, vim links, etc.).
115 var id
: String is writable
118 var title
: nullable String is writable
120 # Does `self` have a `parent`?
121 fun is_root
: Bool do return parent
== null
123 # Children elements contained in `self`.
125 # Children are ordered, this order can be changed by the `DocPhase`.
126 var children
= new Array[DocComposite]
128 # Is `self` not displayed in the page.
130 # By default, empty elements are hidden.
131 fun is_hidden
: Bool do return children
.is_empty
133 # Title used in table of content if any.
134 var toc_title
: nullable String is writable, lazy
do return title
136 # Is `self` hidden in the table of content?
137 var is_toc_hidden
: Bool is writable, lazy
do
138 return toc_title
== null or is_hidden
141 # Add a `child` to `self`.
143 # Shortcut for `children.add`.
144 fun add_child
(child
: DocComposite) do
149 # Depth of `self` in the composite tree.
151 var parent
= self.parent
152 if parent
== null then return 0
153 return parent
.depth
+ 1
156 # Pretty prints this composite recursively.
157 fun pretty_print
: Writable do
158 var res
= new Template
163 # Appends the Pretty print of this composite in `res`.
164 private fun pretty_print_in
(res
: Template) do
168 for child
in children
do child
.pretty_print_in
(res
)
172 # The `DocComposite` element that contains all the other.
174 # The root uses a specific subclass to provide different a different behavior
175 # than other `DocComposite` elements.
180 redef var id
= "<root>"
181 redef var title
= "<root>"
183 # No op for `RootSection`.
184 redef fun parent
=(p
) do end
187 # Base page elements.
189 # `DocSection` are used to break the documentation page into meaningfull parts.
191 # The content of the documentation summary is based on the section structure
192 # contained in the DocComposite tree.
197 # `DocArticle` are pieces of documentation.
199 # They maintains the content (text, list, image...) of a documentation page.
204 # A DocPhase is a step in the production of a Nitdoc documentation.
206 # Phases work from a `DocModel`.
207 # Specific phases are used to populate, organize, enhance and render the content
208 # of the documentation pages.
210 # See `doc_phases` for available DocPhase.
213 # Link to the ToolContext to access Nitdoc tool options.
216 # `DocModel` used by this phase to work.
219 # Starting point of a `DocPhase`.
221 # This is where the behavior of the phase is implemented.
222 # Phases can populate, edit or render the `doc` from here.
223 fun apply
is abstract
226 redef class ToolContext
228 # Directory where the Nitdoc is rendered.
229 var opt_dir
= new OptionString("Output directory", "-d", "--dir")
231 # Shortcut for `opt_dir.value` with default "doc".
232 var output_dir
: String is lazy
do return opt_dir
.value
or else "doc"
236 option_context
.add_option
(opt_dir
)
240 # Catalog properties by kind.
241 class PropertiesByKind
243 var virtual_types
= new PropertyGroup[MVirtualTypeProp]("Virtual types")
246 var constructors
= new PropertyGroup[MMethod]("Contructors")
249 var attributes
= new PropertyGroup[MAttribute]("Attributes")
252 var methods
= new PropertyGroup[MMethod]("Methods")
255 var inner_classes
= new PropertyGroup[MInnerClass]("Inner classes")
259 # Sorted in the order they are displayed to the user.
260 var groups
: SequenceRead[PropertyGroup[MProperty]] = [
265 inner_classes
: PropertyGroup[MProperty]]
267 # Add each the specified property to the appropriate list.
268 init with_elements
(properties
: Collection[MProperty]) do add_all
(properties
)
270 # Add the specified property to the appropriate list.
271 fun add
(property
: MProperty) do
272 if property
isa MMethod then
273 if property
.is_init
then
274 constructors
.add property
278 else if property
isa MVirtualTypeProp then
279 virtual_types
.add property
280 else if property
isa MAttribute then
281 attributes
.add property
282 else if property
isa MInnerClass then
283 inner_classes
.add property
289 # Add each the specified property to the appropriate list.
290 fun add_all
(properties
: Collection[MProperty]) do
291 for p
in properties
do add
(p
)
294 # Sort each group with the specified comparator.
295 fun sort_groups
(comparator
: Comparator) do
296 for g
in groups
do comparator
.sort
(g
)
300 # An ordered list of properties of the same kind.
301 class PropertyGroup[E
: MProperty]
304 # The title of the group, as displayed to the user.
309 # ID used as a unique ID and in file names.
311 # **Must** match the following (POSIX ERE) regular expression:
314 # ^[A-Za-z_][A-Za-z0-9._-]*$
317 # That way, the ID is always a valid URI component and a valid XML name.
318 fun nitdoc_id
: String do return full_name
.to_cmangle
320 # Name displayed in console for debug and tests.
321 fun nitdoc_name
: String do return name
.html_escape
326 # Avoid id conflict with group
327 redef fun nitdoc_id
do
328 var mgroup
= self.mgroup
329 if mgroup
== null then return super
330 return "{mgroup.full_name}::{full_name}".to_cmangle
334 redef class MClassDef
335 redef fun nitdoc_name
do return mclass
.nitdoc_name
339 redef fun nitdoc_name
do return mproperty
.nitdoc_name