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_collect
  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
  30         # Model to generate the documentation for
  31         var model: Model
  32
  33         # Main module of the sources behing documented
  34         var mainmodule: MModule
  35
  36         # Model filters to apply
  37         var filter: ModelFilter
  38
  39         # `DocPage` composing the documentation associated to their ids.
  40         #
  41         # This is where `DocPhase` store and access pages to produce documentation.
  42         #
  43         # See `add_page`.
  44         var pages: Map[String, DocPage] = new HashMap[String, DocPage]
  45
  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}`"
  50                 end
  51                 pages[page.id] = page
  52         end
  53 end
  54
  55 # A documentation page abstraction.
  56 #
  57 # The page contains a link to the `root` of the `DocComposite` that compose the
  58 # the page.
  59 class DocPage
  60
  61         # Page uniq id.
  62         #
  63         # The `id` is used as name for the generated file corresponding to the page
  64         # (if any).
  65         # Because multiple pages can be generated in the same directory it should be
  66         # uniq.
  67         #
  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
  71
  72         # Title of this page.
  73         var title: String is writable
  74
  75         # Root element of the page.
  76         #
  77         # `DocPhase` access the structure of the page from the `DocRoot`.
  78         var root = new DocRoot
  79
  80         redef fun to_s do return title
  81
  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)
  88                 end
  89                 return res
  90         end
  91 end
  92
  93 # `DocPage` elements that can be nested in another.
  94 #
  95 # `DocComposite` is an abstraction for everything that go in a `DocPage` like
  96 # sections, articles, images, lists, graphs...
  97 #
  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
 101 # recursively.
 102 abstract class DocComposite
 103
 104         # Parent element.
 105         var parent: nullable DocComposite = null is writable
 106
 107         # Element uniq id.
 108         #
 109         # The `id` is used as name for the generated element (if any).
 110         # Because multiple elements can be generated in the same container
 111         # it should be uniq.
 112         #
 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
 116
 117         # Item title if any.
 118         var title: nullable String is writable
 119
 120         # Does `self` have a `parent`?
 121         fun is_root: Bool do return parent == null
 122
 123         # Children elements contained in `self`.
 124         #
 125         # Children are ordered, this order can be changed by the `DocPhase`.
 126         var children = new Array[DocComposite]
 127
 128         # Is `self` not displayed in the page.
 129         #
 130         # By default, empty elements are hidden.
 131         fun is_hidden: Bool do return children.is_empty
 132
 133         # Title used in table of content if any.
 134         var toc_title: nullable String is writable, lazy do return title
 135
 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
 139         end
 140
 141         # Add a `child` to `self`.
 142         #
 143         # Shortcut for `children.add`.
 144         fun add_child(child: DocComposite) do
 145                 child.parent = self
 146                 children.add child
 147         end
 148
 149         # Depth of `self` in the composite tree.
 150         fun depth: Int do
 151                 var parent = self.parent
 152                 if parent == null then return 0
 153                 return parent.depth + 1
 154         end
 155
 156         # Pretty prints this composite recursively.
 157         fun pretty_print: Writable do
 158                 var res = new Template
 159                 pretty_print_in(res)
 160                 return res
 161         end
 162
 163         # Appends the Pretty print of this composite in `res`.
 164         private fun pretty_print_in(res: Template) do
 165                 res.add "\t" * depth
 166                 res.add "#" * depth
 167                 res.addn " {id}"
 168                 for child in children do child.pretty_print_in(res)
 169         end
 170 end
 171
 172 # The `DocComposite` element that contains all the other.
 173 #
 174 # The root uses a specific subclass to provide different a different behavior
 175 # than other `DocComposite` elements.
 176 class DocRoot
 177         noautoinit
 178         super DocComposite
 179
 180         redef var id = "<root>"
 181         redef var title = "<root>"
 182
 183         # No op for `RootSection`.
 184         redef fun parent=(p) do end
 185 end
 186
 187 # Base page elements.
 188
 189 # `DocSection` are used to break the documentation page into meaningfull parts.
 190 #
 191 # The content of the documentation summary is based on the section structure
 192 # contained in the DocComposite tree.
 193 class DocSection
 194         super DocComposite
 195 end
 196
 197 # `DocArticle` are pieces of documentation.
 198 #
 199 # They maintains the content (text, list, image...) of a documentation page.
 200 class DocArticle
 201         super DocComposite
 202 end
 203
 204 # A DocPhase is a step in the production of a Nitdoc documentation.
 205 #
 206 # Phases work from a `DocModel`.
 207 # Specific phases are used to populate, organize, enhance and render the content
 208 # of the documentation pages.
 209 #
 210 # See `doc_phases` for available DocPhase.
 211 class DocPhase
 212
 213         # Link to the ToolContext to access Nitdoc tool options.
 214         var ctx: ToolContext
 215
 216         # `DocModel` used by this phase to work.
 217         var doc: DocModel
 218
 219         # Starting point of a `DocPhase`.
 220         #
 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
 224 end
 225
 226 redef class ToolContext
 227
 228         # Directory where the Nitdoc is rendered.
 229         var opt_dir = new OptionString("Output directory", "-d", "--dir")
 230
 231         # Shortcut for `opt_dir.value` with default "doc".
 232         var output_dir: String is lazy do return opt_dir.value or else "doc"
 233
 234         redef init do
 235                 super
 236                 option_context.add_option(opt_dir)
 237         end
 238 end
 239
 240 # Catalog properties by kind.
 241 class PropertiesByKind
 242         # The virtual types.
 243         var virtual_types = new PropertyGroup[MVirtualTypeProp]("Virtual types")
 244
 245         # The constructors.
 246         var constructors = new PropertyGroup[MMethod]("Contructors")
 247
 248         # The attributes.
 249         var attributes = new PropertyGroup[MAttribute]("Attributes")
 250
 251         # The methods.
 252         var methods = new PropertyGroup[MMethod]("Methods")
 253
 254         # The inner classes.
 255         var inner_classes = new PropertyGroup[MInnerClass]("Inner classes")
 256
 257         # All the groups.
 258         #
 259         # Sorted in the order they are displayed to the user.
 260         var groups: SequenceRead[PropertyGroup[MProperty]] = [
 261                         virtual_types,
 262                         constructors,
 263                         attributes,
 264                         methods,
 265                         inner_classes: PropertyGroup[MProperty]]
 266
 267         # Add each the specified property to the appropriate list.
 268         init with_elements(properties: Collection[MProperty]) do add_all(properties)
 269
 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
 275                         else
 276                                 methods.add property
 277                         end
 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
 284                 else
 285                         abort
 286                 end
 287         end
 288
 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)
 292         end
 293
 294         # Sort each group with the specified comparator.
 295         fun sort_groups(comparator: Comparator) do
 296                 for g in groups do comparator.sort(g)
 297         end
 298 end
 299
 300 # An ordered list of properties of the same kind.
 301 class PropertyGroup[E: MProperty]
 302         super Array[E]
 303
 304         # The title of the group, as displayed to the user.
 305         var title: String
 306 end
 307
 308 redef class MEntity
 309         # ID used as a unique ID and in file names.
 310         #
 311         # **Must** match the following (POSIX ERE) regular expression:
 312         #
 313         # ~~~POSIX ERE
 314         # ^[A-Za-z_][A-Za-z0-9._-]*$
 315         # ~~~
 316         #
 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
 319
 320         # Name displayed in console for debug and tests.
 321         fun nitdoc_name: String do return name.html_escape
 322 end
 323
 324 redef class MModule
 325
 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
 331         end
 332 end
 333
 334 redef class MClassDef
 335         redef fun nitdoc_name do return mclass.nitdoc_name
 336 end
 337
 338 redef class MPropDef
 339         redef fun nitdoc_name do return mproperty.nitdoc_name
 340 end