src/doc/doc_base.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   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
   6 #
   7 # http://www.apache.org/licenses/LICENSE-2.0
   8 #
   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.
  14
  15 # Base entities shared by all the nitdoc code.
  16 module doc_base
  17
  18 import toolcontext
  19 import model_ext
  20 import model::model_views
  21
  22 # The model of a Nitdoc documentation.
  23 #
  24 # `DocModel` contains the list of the `DocPage` to be generated.
  25 #
  26 # The model is populated through `DocPhase` to be constructed.
  27 # It is a placeholder to share data between each phase.
  28 class DocModel
  29         super ModelView
  30
  31         autoinit model, mainmodule, filter
  32
  33         # `DocPage` composing the documentation associated to their ids.
  34         #
  35         # This is where `DocPhase` store and access pages to produce documentation.
  36         #
  37         # See `add_page`.
  38         var pages: Map[String, DocPage] = new HashMap[String, DocPage]
  39
  40         # Add a `page` to this documentation.
  41         fun add_page(page: DocPage) do
  42                 if pages.has_key(page.id) then
  43                         print "Warning: multiple page with the same id `{page.id}`"
  44                 end
  45                 pages[page.id] = page
  46         end
  47 end
  48
  49 # A documentation page abstraction.
  50 #
  51 # The page contains a link to the `root` of the `DocComposite` that compose the
  52 # the page.
  53 class DocPage
  54
  55         # Page uniq id.
  56         #
  57         # The `id` is used as name for the generated file corresponding to the page
  58         # (if any).
  59         # Because multiple pages can be generated in the same directory it should be
  60         # uniq.
  61         #
  62         # The `id` can also be used to establish links between pages (HTML links,
  63         # HTML anchors, vim links, etc.).
  64         var id: String is writable
  65
  66         # Title of this page.
  67         var title: String is writable
  68
  69         # Root element of the page.
  70         #
  71         # `DocPhase` access the structure of the page from the `DocRoot`.
  72         var root = new DocRoot
  73
  74         redef fun to_s do return title
  75
  76         # Pretty prints the content of this page.
  77         fun pretty_print: Writable do
  78                 var res = new Template
  79                 res.addn "{class_name} {title}"
  80                 for child in root.children do
  81                         child.pretty_print_in(res)
  82                 end
  83                 return res
  84         end
  85 end
  86
  87 # `DocPage` elements that can be nested in another.
  88 #
  89 # `DocComposite` is an abstraction for everything that go in a `DocPage` like
  90 # sections, articles, images, lists, graphs...
  91 #
  92 # It provides base services for nesting mechanisms following the
  93 # *Composite pattern*.
  94 # The composed structure is a tree from a `DocRoot` that can be manipulated
  95 # recursively.
  96 abstract class DocComposite
  97
  98         # Parent element.
  99         var parent: nullable DocComposite = null is writable
 100
 101         # Element uniq id.
 102         #
 103         # The `id` is used as name for the generated element (if any).
 104         # Because multiple elements can be generated in the same container
 105         # it should be uniq.
 106         #
 107         # The `id` can also be used to establish links between elements
 108         # (HTML links, HTML anchors, vim links, etc.).
 109         var id: String is writable
 110
 111         # Item title if any.
 112         var title: nullable String is writable
 113
 114         # Does `self` have a `parent`?
 115         fun is_root: Bool do return parent == null
 116
 117         # Children elements contained in `self`.
 118         #
 119         # Children are ordered, this order can be changed by the `DocPhase`.
 120         var children = new Array[DocComposite]
 121
 122         # Is `self` not displayed in the page.
 123         #
 124         # By default, empty elements are hidden.
 125         fun is_hidden: Bool do return children.is_empty
 126
 127         # Title used in table of content if any.
 128         var toc_title: nullable String is writable, lazy do return title
 129
 130         # Is `self` hidden in the table of content?
 131         var is_toc_hidden: Bool is writable, lazy do
 132                 return toc_title == null or is_hidden
 133         end
 134
 135         # Add a `child` to `self`.
 136         #
 137         # Shortcut for `children.add`.
 138         fun add_child(child: DocComposite) do
 139                 child.parent = self
 140                 children.add child
 141         end
 142
 143         # Depth of `self` in the composite tree.
 144         fun depth: Int do
 145                 var parent = self.parent
 146                 if parent == null then return 0
 147                 return parent.depth + 1
 148         end
 149
 150         # Pretty prints this composite recursively.
 151         fun pretty_print: Writable do
 152                 var res = new Template
 153                 pretty_print_in(res)
 154                 return res
 155         end
 156
 157         # Appends the Pretty print of this composite in `res`.
 158         private fun pretty_print_in(res: Template) do
 159                 res.add "\t" * depth
 160                 res.add "#" * depth
 161                 res.addn " {id}"
 162                 for child in children do child.pretty_print_in(res)
 163         end
 164 end
 165
 166 # The `DocComposite` element that contains all the other.
 167 #
 168 # The root uses a specific subclass to provide different a different behavior
 169 # than other `DocComposite` elements.
 170 class DocRoot
 171         noautoinit
 172         super DocComposite
 173
 174         redef var id = "<root>"
 175         redef var title = "<root>"
 176
 177         # No op for `RootSection`.
 178         redef fun parent=(p) do end
 179 end
 180
 181 # Base page elements.
 182
 183 # `DocSection` are used to break the documentation page into meaningfull parts.
 184 #
 185 # The content of the documentation summary is based on the section structure
 186 # contained in the DocComposite tree.
 187 class DocSection
 188         super DocComposite
 189 end
 190
 191 # `DocArticle` are pieces of documentation.
 192 #
 193 # They maintains the content (text, list, image...) of a documentation page.
 194 class DocArticle
 195         super DocComposite
 196 end
 197
 198 # A DocPhase is a step in the production of a Nitdoc documentation.
 199 #
 200 # Phases work from a `DocModel`.
 201 # Specific phases are used to populate, organize, enhance and render the content
 202 # of the documentation pages.
 203 #
 204 # See `doc_phases` for available DocPhase.
 205 class DocPhase
 206
 207         # Link to the ToolContext to access Nitdoc tool options.
 208         var ctx: ToolContext
 209
 210         # `DocModel` used by this phase to work.
 211         var doc: DocModel
 212
 213         # Starting point of a `DocPhase`.
 214         #
 215         # This is where the behavior of the phase is implemented.
 216         # Phases can populate, edit or render the `doc` from here.
 217         fun apply is abstract
 218 end
 219
 220 redef class ToolContext
 221
 222         # Directory where the Nitdoc is rendered.
 223         var opt_dir = new OptionString("Output directory", "-d", "--dir")
 224
 225         # Shortcut for `opt_dir.value` with default "doc".
 226         var output_dir: String is lazy do return opt_dir.value or else "doc"
 227
 228         redef init do
 229                 super
 230                 option_context.add_option(opt_dir)
 231         end
 232 end
 233
 234 # Catalog properties by kind.
 235 class PropertiesByKind
 236         # The virtual types.
 237         var virtual_types = new PropertyGroup[MVirtualTypeProp]("Virtual types")
 238
 239         # The constructors.
 240         var constructors = new PropertyGroup[MMethod]("Contructors")
 241
 242         # The attributes.
 243         var attributes = new PropertyGroup[MAttribute]("Attributes")
 244
 245         # The methods.
 246         var methods = new PropertyGroup[MMethod]("Methods")
 247
 248         # The inner classes.
 249         var inner_classes = new PropertyGroup[MInnerClass]("Inner classes")
 250
 251         # All the groups.
 252         #
 253         # Sorted in the order they are displayed to the user.
 254         var groups: SequenceRead[PropertyGroup[MProperty]] = [
 255                         virtual_types,
 256                         constructors,
 257                         attributes,
 258                         methods,
 259                         inner_classes: PropertyGroup[MProperty]]
 260
 261         # Add each the specified property to the appropriate list.
 262         init with_elements(properties: Collection[MProperty]) do add_all(properties)
 263
 264         # Add the specified property to the appropriate list.
 265         fun add(property: MProperty) do
 266                 if property isa MMethod then
 267                         if property.is_init then
 268                                 constructors.add property
 269                         else
 270                                 methods.add property
 271                         end
 272                 else if property isa MVirtualTypeProp then
 273                         virtual_types.add property
 274                 else if property isa MAttribute then
 275                         attributes.add property
 276                 else if property isa MInnerClass then
 277                         inner_classes.add property
 278                 else
 279                         abort
 280                 end
 281         end
 282
 283         # Add each the specified property to the appropriate list.
 284         fun add_all(properties: Collection[MProperty]) do
 285                 for p in properties do add(p)
 286         end
 287
 288         # Sort each group with the specified comparator.
 289         fun sort_groups(comparator: Comparator) do
 290                 for g in groups do comparator.sort(g)
 291         end
 292 end
 293
 294 # An ordered list of properties of the same kind.
 295 class PropertyGroup[E: MProperty]
 296         super Array[E]
 297
 298         # The title of the group, as displayed to the user.
 299         var title: String
 300 end
 301
 302 redef class MEntity
 303         # ID used as a unique ID and in file names.
 304         #
 305         # **Must** match the following (POSIX ERE) regular expression:
 306         #
 307         # ~~~POSIX ERE
 308         # ^[A-Za-z_][A-Za-z0-9._-]*$
 309         # ~~~
 310         #
 311         # That way, the ID is always a valid URI component and a valid XML name.
 312         fun nitdoc_id: String do return full_name.to_cmangle
 313
 314         # Name displayed in console for debug and tests.
 315         fun nitdoc_name: String do return name.html_escape
 316 end
 317
 318 redef class MModule
 319
 320         # Avoid id conflict with group
 321         redef fun nitdoc_id do
 322                 var mgroup = self.mgroup
 323                 if mgroup == null then return super
 324                 return "{mgroup.full_name}::{full_name}".to_cmangle
 325         end
 326 end
 327
 328 redef class MClassDef
 329         redef fun nitdoc_name do return mclass.nitdoc_name
 330 end
 331
 332 redef class MPropDef
 333         redef fun nitdoc_name do return mproperty.nitdoc_name
 334 end