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