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