src/doc/templates/templates_html.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 # Translate mentities to html blocks.
  16 module templates_html
  17
  18 import model::model_collect
  19 import doc::doc_down
  20 import html::bootstrap
  21
  22 redef class MEntity
  23
  24         # The MEntity unique ID in the HTML output
  25         var html_id: String is lazy do return full_name.to_cmangle
  26
  27         # The MEntity URL in the HTML output
  28         #
  29         # You MUST redefine this method.
  30         # Depending on your implementation, this URL can be a page URL or an anchor.
  31         var html_url: String is lazy do return html_id
  32
  33         # The MEntity name escaped for HTML
  34         var html_name: String is lazy do return name.html_escape
  35
  36         # The MEntity `full_name` escaped for HTML
  37         var html_full_name: String is lazy do return full_name.html_escape
  38
  39         # Link to the MEntity in the HTML output
  40         #
  41         # You should redefine this method depending on the organization or your
  42         # output.
  43         fun html_link: Link do
  44                 var title = null
  45                 var mdoc = self.mdoc_or_fallback
  46                 if mdoc != null then
  47                         title = mdoc.synopsis.html_escape
  48                 end
  49                 return new Link(html_url, html_name, title)
  50         end
  51
  52         # Returns the complete MEntity declaration decorated with HTML
  53         #
  54         # Examples:
  55         # * MPackage: `package foo`
  56         # * MGroup: `group foo`
  57         # * MModule: `module foo`
  58         # * MClass: `private abstract class Foo[E: Object]`
  59         # * MClassDef: `redef class Foo[E]`
  60         # * MProperty: `private fun foo(e: Object): Int`
  61         # * MPropdef: `redef fun foo(e)`
  62         fun html_declaration: Template do
  63                 var tpl = new Template
  64                 tpl.add "<span class='signature'>"
  65                 for modifier in collect_modifiers do
  66                         tpl.add "<span class='modifier'>{modifier}</span>&nbsp;"
  67                 end
  68                 tpl.add "<span class='name'>{html_link.write_to_string}</span>"
  69                 tpl.add html_signature(false)
  70                 tpl.add "</span>"
  71                 return tpl
  72         end
  73
  74         # Returns the MEntity signature decorated with HTML
  75         #
  76         # This function only returns the parenthesis and return types.
  77         # See `html_declaration` for the full declaration including modifiers and name.
  78         fun html_signature(short: nullable Bool): Template do return new Template
  79
  80         # Returns `full_name` decorated with HTML links
  81         fun html_namespace: Template is abstract
  82
  83         # An icon representative of the mentity
  84         fun html_icon: BSIcon do return new BSIcon("tag", ["text-muted"])
  85
  86         # A li element that can go in a `HTMLList`
  87         fun html_list_item: ListItem do
  88                 var tpl = new Template
  89                 tpl.add html_namespace
  90                 var comment = mdoc_or_fallback
  91                 if comment != null then
  92                         tpl.add ": "
  93                         tpl.add comment.html_synopsis
  94                 end
  95                 return new ListItem(tpl)
  96         end
  97
  98         # CSS classes used to decorate `self`
  99         #
 100         # Mainly used for icons.
 101         var css_classes: Array[String] = collect_modifiers is lazy
 102 end
 103
 104 redef class MPackage
 105         redef fun html_url do return "package_{html_id}.html"
 106         redef fun html_namespace do return html_link
 107         redef fun html_icon do return new BSIcon("book", ["text-muted"])
 108         redef var css_classes = ["public"]
 109 end
 110
 111 redef class MGroup
 112         redef fun html_url do return "group_{html_id}.html"
 113         redef fun html_icon do return new BSIcon("folder-close", ["text-muted"])
 114
 115         redef fun html_namespace do
 116                 var tpl = new Template
 117                 var parent = self.parent
 118                 if parent != null then
 119                         tpl.add parent.html_namespace
 120                         tpl.add " > "
 121                 end
 122                 tpl.add html_link
 123                 return tpl
 124         end
 125 end
 126
 127 redef class MModule
 128         redef fun html_url do return "module_{html_id}.html"
 129         redef fun html_icon do return new BSIcon("file", ["text-muted"])
 130
 131         redef fun html_namespace do
 132                 var mpackage = self.mpackage
 133                 var tpl = new Template
 134                 if mpackage != null then
 135                         tpl.add mpackage.html_namespace
 136                         tpl.add " :: "
 137                 end
 138                 tpl.add html_link
 139                 return tpl
 140         end
 141 end
 142
 143 redef class MClass
 144         redef fun html_url do return "class_{html_id}.html"
 145         redef fun html_icon do return new BSIcon("stop", css_classes)
 146         redef fun html_signature(short) do return intro.html_signature(short)
 147         redef fun css_classes do return super + [visibility.to_s]
 148
 149         redef fun html_namespace do
 150                 var mgroup = intro_mmodule.mgroup
 151                 var tpl = new Template
 152                 if mgroup != null then
 153                         tpl.add mgroup.mpackage.html_namespace
 154                         tpl.add " :: "
 155                 end
 156                 tpl.add "<span>"
 157                 tpl.add html_link
 158                 tpl.add "</span>"
 159                 return tpl
 160         end
 161 end
 162
 163 redef class MClassDef
 164         redef fun html_url do return "{mclass.html_url}#{html_id}"
 165         redef fun css_classes do return super + mclass.css_classes
 166
 167         redef fun html_namespace do
 168                 var tpl = new Template
 169                 var mpackage = mmodule.mpackage
 170                 if mpackage != null and is_intro then
 171                         if is_intro then
 172                                 tpl.add mpackage.html_namespace
 173                                 tpl.add " $ "
 174                         else
 175                                 tpl.add mmodule.html_namespace
 176                                 tpl.add " $ "
 177                                 var intro_mpackage = mclass.intro.mmodule.mpackage
 178                                 if intro_mpackage != null and mpackage != intro_mpackage then
 179                                         tpl.add intro_mpackage.html_namespace
 180                                         tpl.add " :: "
 181                                 end
 182                         end
 183                 else
 184                         tpl.add mmodule.html_namespace
 185                         tpl.add " $ "
 186                 end
 187                 tpl.add html_link
 188                 return tpl
 189         end
 190
 191         redef fun html_icon do
 192                 if is_intro then
 193                         return new BSIcon("plus", css_classes)
 194                 end
 195                 return new BSIcon("asterisk", css_classes)
 196         end
 197
 198         redef fun html_signature(short) do
 199                 var tpl = new Template
 200                 var mparameters = mclass.mparameters
 201                 if not mparameters.is_empty then
 202                         tpl.add "["
 203                         for i in [0..mparameters.length[ do
 204                                 tpl.add mparameters[i].html_name
 205                                 if short == null or not short then
 206                                         tpl.add ": "
 207                                         tpl.add bound_mtype.arguments[i].html_signature(short)
 208                                 end
 209                                 if i < mparameters.length - 1 then tpl.add ", "
 210                         end
 211                         tpl.add "]"
 212                 end
 213                 return tpl
 214         end
 215 end
 216
 217 redef class MProperty
 218         redef fun html_url do return "property_{html_id}.html"
 219         redef fun html_declaration do return intro.html_declaration
 220         redef fun html_signature(short) do return intro.html_signature(short)
 221         redef fun html_icon do return new BSIcon("tag", css_classes)
 222         redef fun css_classes do return super + [visibility.to_s]
 223
 224         redef fun html_namespace do
 225                 var tpl = new Template
 226                 tpl.add intro_mclassdef.mclass.html_namespace
 227                 tpl.add " :: "
 228                 tpl.add intro.html_link
 229                 return tpl
 230         end
 231 end
 232
 233 redef class MPropDef
 234         redef fun html_url do return "{mproperty.html_url}#{html_id}"
 235         redef fun css_classes do return super + mproperty.css_classes
 236
 237         redef fun html_namespace do
 238                 var tpl = new Template
 239                 tpl.add mclassdef.html_namespace
 240                 tpl.add " :: "
 241                 tpl.add html_link
 242                 return tpl
 243         end
 244
 245         redef fun html_icon do
 246                 if is_intro then
 247                         return new BSIcon("plus", css_classes)
 248                 end
 249                 return new BSIcon("asterisk", css_classes)
 250         end
 251 end
 252
 253 redef class MAttributeDef
 254         redef fun html_signature(short) do
 255                 var static_mtype = self.static_mtype
 256                 var tpl = new Template
 257                 if static_mtype != null then
 258                         tpl.add ": "
 259                         tpl.add static_mtype.html_signature(short)
 260                 end
 261                 return tpl
 262         end
 263 end
 264
 265 redef class MMethodDef
 266         redef fun html_signature(short) do
 267                 var new_msignature = self.new_msignature
 268                 if mproperty.is_root_init and new_msignature != null then
 269                         return new_msignature.html_signature(short)
 270                 end
 271                 return msignature.as(not null).html_signature(short)
 272         end
 273 end
 274
 275 redef class MVirtualTypeProp
 276         redef fun html_link do return mvirtualtype.html_link
 277 end
 278
 279 redef class MVirtualTypeDef
 280         redef fun html_signature(short) do
 281                 var bound = self.bound
 282                 var tpl = new Template
 283                 if bound == null then return tpl
 284                 tpl.add ": "
 285                 tpl.add bound.html_signature(short)
 286                 return tpl
 287         end
 288 end
 289
 290 redef class MType
 291         redef fun html_signature(short) do return html_link
 292 end
 293
 294 redef class MClassType
 295         redef fun html_link do return mclass.html_link
 296 end
 297
 298 redef class MNullableType
 299         redef fun html_signature(short) do
 300                 var tpl = new Template
 301                 tpl.add "nullable "
 302                 tpl.add mtype.html_signature(short)
 303                 return tpl
 304         end
 305 end
 306
 307 redef class MGenericType
 308         redef fun html_signature(short) do
 309                 var lnk = html_link
 310                 var tpl = new Template
 311                 tpl.add new Link(lnk.href, mclass.name.html_escape, lnk.title)
 312                 tpl.add "["
 313                 for i in [0..arguments.length[ do
 314                         tpl.add arguments[i].html_signature(short)
 315                         if i < arguments.length - 1 then tpl.add ", "
 316                 end
 317                 tpl.add "]"
 318                 return tpl
 319         end
 320 end
 321
 322 redef class MParameterType
 323         redef fun html_link do
 324                 return new Link("{mclass.html_url}#FT_{name.to_cmangle}", name, "formal type")
 325         end
 326 end
 327
 328 redef class MVirtualType
 329         redef fun html_link do return mproperty.intro.html_link
 330 end
 331
 332 redef class MSignature
 333         redef fun html_signature(short) do
 334                 var tpl = new Template
 335                 if not mparameters.is_empty then
 336                         tpl.add "("
 337                         for i in [0..mparameters.length[ do
 338                                 tpl.add mparameters[i].html_signature(short)
 339                                 if i < mparameters.length - 1 then tpl.add ", "
 340                         end
 341                         tpl.add ")"
 342                 end
 343                 if short == null or not short then
 344                         var return_mtype = self.return_mtype
 345                         if return_mtype != null then
 346                                 tpl.add ": "
 347                                 tpl.add return_mtype.html_signature(short)
 348                         end
 349                 end
 350                 return tpl
 351         end
 352 end
 353
 354 redef class MParameter
 355         redef fun html_signature(short) do
 356                 var tpl = new Template
 357                 tpl.add name
 358                 if short == null or not short then
 359                         tpl.add ": "
 360                         tpl.add mtype.html_signature(short)
 361                 end
 362                 if is_vararg then tpl.add "..."
 363                 return tpl
 364         end
 365 end