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 doc_model # FIXME maintain compatibility with old templates.
  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.
  30         #
  31         # This is where `DocPhase` store and access pages to produce documentation.
  32         var pages = new Array[DocPage]
  33
  34         # Nit `Model` from which we extract the documentation.
  35         var model: Model is writable
  36
  37         # The entry point of the `model`.
  38         var mainmodule: MModule is writable
  39 end
  40
  41 # A documentation page abstraction.
  42 #
  43 # The page contains a link to the `root` of the `DocComposite` that compose the
  44 # the page.
  45 class DocPage
  46
  47         # Title of this page.
  48         var title: String is writable
  49
  50         # Root element of the page.
  51         #
  52         # `DocPhase` access the structure of the page from the `DocRoot`.
  53         var root = new DocRoot
  54
  55         redef fun to_s do return title
  56 end
  57
  58 # `DocPage` elements that can be nested in another.
  59 #
  60 # `DocComposite` is an abstraction for everything that go in a `DocPage` like
  61 # sections, articles, images, lists, graphs...
  62 #
  63 # It provides base services for nesting mechanisms following the
  64 # *Composite pattern*.
  65 # The composed structure is a tree from a `DocRoot` that can be manipulated
  66 # recursively.
  67 abstract class DocComposite
  68
  69         # Parent element.
  70         var parent: nullable DocComposite = null
  71
  72         # Does `self` have a `parent`?
  73         fun is_root: Bool do return parent == null
  74
  75         # Children elements contained in `self`.
  76         #
  77         # Children are ordered, this order can be changed by the `DocPhase`.
  78         var children = new Array[DocComposite]
  79
  80         # Does `self` have `children`?
  81         fun is_empty: Bool do return children.is_empty
  82
  83         # Add a `child` to `self`.
  84         #
  85         # Shortcut for `children.add`.
  86         fun add(child: DocComposite) do children.add child
  87 end
  88
  89 # The `DocComposite` element that contains all the other.
  90 #
  91 # The root uses a specific subclass to provide different a different behavior
  92 # than other `DocComposite` elements.
  93 class DocRoot
  94         super DocComposite
  95
  96         # No op for `RootSection`.
  97         redef fun parent=(p) do end
  98 end
  99
 100 # Base page elements.
 101
 102 # `DocSection` are used to break the documentation page into meaningfull parts.
 103 #
 104 # The content of the documentation summary is based on the section structure
 105 # contained in the DocComposite tree.
 106 class DocSection
 107         super DocComposite
 108 end
 109
 110 # `DocArticle` are pieces of documentation.
 111 #
 112 # They maintains the content (text, list, image...) of a documentation page.
 113 class DocArticle
 114         super DocComposite
 115 end
 116
 117 # A DocPhase is a step in the production of a Nitdoc documentation.
 118 #
 119 # Phases work from a `DocModel`.
 120 # Specific phases are used to populate, organize, enhance and render the content
 121 # of the documentation pages.
 122 #
 123 # See `doc_phases` for available DocPhase.
 124 class DocPhase
 125
 126         # Link to the ToolContext to access Nitdoc tool options.
 127         var ctx: ToolContext
 128
 129         # `DocModel` used by this phase to work.
 130         var doc: DocModel
 131
 132         # Starting point of a `DocPhase`.
 133         #
 134         # This is where the behavior of the phase is implemented.
 135         # Phases can populate, edit or render the `doc` from here.
 136         fun apply is abstract
 137 end
 138
 139 redef class ToolContext
 140
 141         # Directory where the Nitdoc is rendered.
 142         var opt_dir = new OptionString("output directory", "-d", "--dir")
 143
 144         # Shortcut for `opt_dir.value` with default "doc".
 145         var output_dir: String is lazy do return opt_dir.value or else "doc"
 146
 147         redef init do
 148                 super
 149                 option_context.add_option(opt_dir)
 150         end
 151 end
 152
 153 # Catalog properties by kind.
 154 class PropertiesByKind
 155         # The virtual types.
 156         var virtual_types = new PropertyGroup[MVirtualTypeProp]("Virtual types")
 157
 158         # The constructors.
 159         var constructors = new PropertyGroup[MMethod]("Contructors")
 160
 161         # The attributes.
 162         var attributes = new PropertyGroup[MAttribute]("Attributes")
 163
 164         # The methods.
 165         var methods = new PropertyGroup[MMethod]("Methods")
 166
 167         # The inner classes.
 168         var inner_classes = new PropertyGroup[MInnerClass]("Inner classes")
 169
 170         # All the groups.
 171         #
 172         # Sorted in the order they are displayed to the user.
 173         var groups: SequenceRead[PropertyGroup[MProperty]] = [
 174                         virtual_types,
 175                         constructors,
 176                         attributes,
 177                         methods,
 178                         inner_classes: PropertyGroup[MProperty]]
 179
 180         # Add each the specified property to the appropriate list.
 181         init with_elements(properties: Collection[MProperty]) do add_all(properties)
 182
 183         # Add the specified property to the appropriate list.
 184         fun add(property: MProperty) do
 185                 if property isa MMethod then
 186                         if property.is_init then
 187                                 constructors.add property
 188                         else
 189                                 methods.add property
 190                         end
 191                 else if property isa MVirtualTypeProp then
 192                         virtual_types.add property
 193                 else if property isa MAttribute then
 194                         attributes.add property
 195                 else if property isa MInnerClass then
 196                         inner_classes.add property
 197                 else
 198                         abort
 199                 end
 200         end
 201
 202         # Add each the specified property to the appropriate list.
 203         fun add_all(properties: Collection[MProperty]) do
 204                 for p in properties do add(p)
 205         end
 206
 207         # Sort each group with the specified comparator.
 208         fun sort_groups(comparator: Comparator) do
 209                 for g in groups do comparator.sort(g)
 210         end
 211 end
 212
 213 # An ordered list of properties of the same kind.
 214 class PropertyGroup[E: MProperty]
 215         super Array[E]
 216
 217         # The title of the group, as displayed to the user.
 218         var title: String
 219 end