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