src/doc/doc_model.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 # Nitdoc model template parts generation
  16 module doc_model
  17
  18 import model_utils
  19 import markdown
  20 import doc_templates
  21 import ordered_tree
  22
  23 redef class MDoc
  24         # Comment synopsys HTML escaped
  25         fun short_comment: String do return content.first.html_escape
  26
  27         # Full comment HTML escaped
  28         fun full_comment: String do return content.join("\n").html_escape
  29
  30         # Synopsys in a template
  31         fun tpl_short_comment: Streamable do return short_markdown
  32
  33         # Full comment in a template
  34         fun tpl_comment: Streamable do return full_markdown
  35 end
  36
  37 redef class Location
  38         # Github url based on this location
  39         fun github(gitdir: String): String do
  40                 var base_dir = getcwd.join_path(gitdir).simplify_path
  41                 var file_loc = getcwd.join_path(file.filename).simplify_path
  42                 var gith_loc = file_loc.substring(base_dir.length + 1, file_loc.length)
  43                 return "{gith_loc}:{line_start},{column_start}--{line_end},{column_end}"
  44         end
  45 end
  46
  47 redef class MEntity
  48         # HTML Escaped name
  49         fun nitdoc_name: String is abstract
  50
  51         # Used as HTML unique ids
  52         fun nitdoc_id: String is abstract
  53
  54         # URL of this entity Nitdoc page
  55         fun nitdoc_url: String is abstract
  56
  57         # A template link to the mentity `nitdoc_id`
  58         fun tpl_anchor: TplLink do
  59                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
  60                 if mdoc != null then
  61                         tpl.title = mdoc.short_comment
  62                 end
  63                 return tpl
  64         end
  65
  66         # A template link to the mentity `nitdoc_url`
  67         fun tpl_link: TplLink do
  68                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
  69                 if mdoc != null then
  70                         tpl.title = mdoc.short_comment
  71                 end
  72                 return tpl
  73         end
  74
  75         # A template article that briefly describe the entity
  76         fun tpl_short_article: TplArticle do
  77                 var tpl = tpl_article
  78                 if mdoc != null then
  79                         tpl.content = mdoc.tpl_short_comment
  80                 end
  81                 return tpl
  82         end
  83
  84         # A template article that describe the entity
  85         fun tpl_article: TplArticle do
  86                 var tpl = new TplArticle.with_title(nitdoc_id, tpl_title)
  87                 tpl.title_classes.add "signature"
  88                 tpl.subtitle = tpl_namespace
  89                 tpl.summary_title = nitdoc_name
  90                 return tpl
  91         end
  92
  93         # A template signature that contains modifiers and parameters
  94         fun tpl_declaration: Template is abstract
  95
  96         # A template namespace
  97         fun tpl_namespace: Template is abstract
  98
  99         # A template definition of the mentity
 100         # include name, sysnopsys, comment and namespace
 101         fun tpl_definition: TplDefinition is abstract
 102
 103         # A li element that can go in a list
 104         fun tpl_list_item: TplListItem do
 105                 var lnk = new Template
 106                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 107                 lnk.add tpl_link
 108                 if mdoc != null then
 109                         lnk.add ": "
 110                         lnk.add mdoc.short_markdown
 111                 end
 112                 return new TplListItem.with_content(lnk)
 113         end
 114
 115         fun tpl_css_classes: Array[String] is abstract
 116
 117         # Box title for this mentity
 118         fun tpl_title: Template do
 119                 var title = new Template
 120                 title.add tpl_icon
 121                 title.add tpl_namespace
 122                 return title
 123         end
 124
 125         # Icon that will be displayed before the title
 126         fun tpl_icon: TplIcon do
 127                 var icon = new TplIcon.with_icon("tag")
 128                 icon.css_classes.add_all(tpl_css_classes)
 129                 return icon
 130         end
 131 end
 132
 133 redef class MConcern
 134         # Return a li element for `self` that can be displayed in a concern list
 135         private fun tpl_concern_item: TplListItem do
 136                 var lnk = new Template
 137                 lnk.add tpl_anchor
 138                 if mdoc != null then
 139                         lnk.add ": "
 140                         lnk.add mdoc.short_markdown
 141                 end
 142                 return new TplListItem.with_content(lnk)
 143         end
 144 end
 145
 146 redef class MProject
 147         redef fun nitdoc_name do return name.html_escape
 148         redef fun nitdoc_id do return nitdoc_name
 149         redef fun nitdoc_url do return root.nitdoc_url
 150
 151         redef fun mdoc do
 152                 if root != null then
 153                         return root.mdoc
 154                 end
 155                 return super
 156         end
 157
 158         redef fun tpl_declaration do
 159                 var tpl = new Template
 160                 tpl.add "<span>project "
 161                 tpl.add tpl_link
 162                 tpl.add "</span>"
 163                 return tpl
 164         end
 165
 166         redef fun tpl_namespace do return tpl_link
 167
 168         redef fun tpl_definition do
 169                 var tpl = new TplDefinition
 170                 if mdoc != null then
 171                         tpl.comment = mdoc.tpl_comment
 172                 end
 173                 return tpl
 174         end
 175
 176         redef fun tpl_css_classes do return ["public"]
 177 end
 178
 179 redef class MGroup
 180         redef fun nitdoc_name do return name.html_escape
 181
 182         redef fun nitdoc_id do
 183                 if parent != null then
 184                         return "{parent.nitdoc_id}__{nitdoc_name}"
 185                 end
 186                 return "{mproject.nitdoc_id}__{nitdoc_name}"
 187         end
 188
 189         redef fun nitdoc_url do return "group_{nitdoc_id}.html"
 190
 191         redef fun tpl_namespace do
 192                 var tpl = new Template
 193                 tpl.add mproject.tpl_namespace
 194                 if mproject.root != self then
 195                         tpl.add "::"
 196                         tpl.add tpl_link
 197                 end
 198                 return tpl
 199         end
 200
 201         redef fun tpl_declaration do
 202                 var tpl = new Template
 203                 tpl.add "<span>group "
 204                 tpl.add tpl_link
 205                 tpl.add "</span>"
 206                 return tpl
 207         end
 208
 209         redef fun tpl_definition do
 210                 var tpl = new TplDefinition
 211                 if mdoc != null then
 212                         tpl.comment = mdoc.tpl_comment
 213                 end
 214                 return tpl
 215         end
 216 end
 217
 218 redef class MModule
 219         redef fun nitdoc_name do return name.html_escape
 220
 221         redef fun nitdoc_id do
 222                 if mgroup != null then
 223                         return "{mgroup.nitdoc_id}__{nitdoc_name}"
 224                 end
 225                 return nitdoc_name
 226         end
 227
 228         redef fun nitdoc_url do return "module_{nitdoc_id}.html"
 229
 230         redef fun tpl_declaration do
 231                 var tpl = new Template
 232                 tpl.add "<span>module "
 233                 tpl.add tpl_link
 234                 tpl.add "</span>"
 235                 return tpl
 236         end
 237
 238         redef fun tpl_namespace do
 239                 var tpl = new Template
 240                 if mgroup != null then
 241                         tpl.add mgroup.tpl_namespace
 242                         tpl.add "::"
 243                 end
 244                 tpl.add tpl_link
 245                 return tpl
 246         end
 247
 248         redef fun tpl_definition do
 249                 var tpl = new TplClassDefinition
 250                 if mdoc != null then
 251                         tpl.comment = mdoc.tpl_comment
 252                 end
 253                 return tpl
 254         end
 255
 256         redef fun tpl_css_classes do return ["public"]
 257 end
 258
 259 redef class MClass
 260         redef fun nitdoc_name do return name.html_escape
 261         redef fun nitdoc_id do return "{intro_mmodule.mgroup.mproject}__{name.to_cmangle}"
 262         redef fun nitdoc_url do return "class_{nitdoc_id}.html"
 263         redef fun mdoc do return intro.mdoc
 264
 265         redef fun tpl_declaration do return intro.tpl_declaration
 266
 267         redef fun tpl_namespace do
 268                 var tpl = new Template
 269                 tpl.add intro_mmodule.mgroup.mproject.tpl_namespace
 270                 tpl.add "::<span>"
 271                 tpl.add tpl_link
 272                 tpl.add "</span>"
 273                 return tpl
 274         end
 275
 276         redef fun tpl_title do
 277                 var title = new Template
 278                 title.add tpl_icon
 279                 title.add tpl_link
 280                 title.add tpl_signature
 281                 return title
 282         end
 283
 284         redef fun tpl_icon do return intro.tpl_icon
 285
 286         fun tpl_signature: Template do
 287                 var tpl = new Template
 288                 if arity > 0 then
 289                         tpl.add "["
 290                         var parameter_names = new Array[String]
 291                         for p in mparameters do
 292                                 parameter_names.add(p.name)
 293                         end
 294                         tpl.add parameter_names.join(", ")
 295                         tpl.add "]"
 296                 end
 297                 return tpl
 298         end
 299
 300         redef fun tpl_article do
 301                 var tpl = super
 302                 tpl.summary_title = "{nitdoc_name}{tpl_signature.write_to_string}"
 303                 return tpl
 304         end
 305
 306         redef fun tpl_css_classes do return intro.tpl_css_classes
 307 end
 308
 309 redef class MClassDef
 310         redef fun nitdoc_name do return mclass.nitdoc_name
 311         redef fun nitdoc_id do return "{mmodule.nitdoc_id}__{name.to_cmangle}"
 312         redef fun nitdoc_url do return "{mclass.nitdoc_url}#{nitdoc_id}"
 313
 314         redef fun tpl_namespace do
 315                 var tpl = new Template
 316                 tpl.add mmodule.tpl_namespace
 317                 tpl.add "::<span>"
 318                 tpl.add mclass.tpl_link
 319                 tpl.add "</span>"
 320                 return tpl
 321         end
 322
 323         redef fun tpl_article do
 324                 var tpl = new TplArticle(nitdoc_id)
 325                 tpl.summary_title = "in {mmodule.nitdoc_name}"
 326                 tpl.title = tpl_declaration
 327                 tpl.title_classes.add "signature"
 328                 var title = new Template
 329                 title.add "in "
 330                 title.add mmodule.tpl_namespace
 331                 tpl.subtitle = title
 332                 if mdoc != null then
 333                         tpl.content = mdoc.tpl_comment
 334                 end
 335                 return tpl
 336         end
 337
 338         redef fun tpl_title do
 339                 var title = new Template
 340                 title.add tpl_icon
 341                 title.add tpl_link
 342                 title.add tpl_signature
 343                 return title
 344         end
 345
 346         redef fun tpl_declaration do
 347                 var tpl = new Template
 348                 tpl.add tpl_modifiers
 349                 tpl.add tpl_link
 350                 tpl.add tpl_signature
 351                 return tpl
 352         end
 353
 354         fun tpl_signature: Template do
 355                 var tpl = new Template
 356                 var mparameters = mclass.mparameters
 357                 if not mparameters.is_empty then
 358                         tpl.add "["
 359                         for i in [0..mparameters.length[ do
 360                                 tpl.add "{mparameters[i].name}: "
 361                                 tpl.add bound_mtype.arguments[i].tpl_signature
 362                                 if i < mparameters.length - 1 then tpl.add ", "
 363                         end
 364                         tpl.add "]"
 365                 end
 366                 return tpl
 367         end
 368
 369         redef fun tpl_definition do
 370                 var tpl = new TplClassDefinition
 371                 tpl.namespace = tpl_namespace
 372                 if mdoc != null then
 373                         tpl.comment = mdoc.tpl_comment
 374                 end
 375                 return tpl
 376         end
 377
 378         redef fun tpl_css_classes do
 379                 var set = new HashSet[String]
 380                 if is_intro then set.add "intro"
 381                 set.add_all mclass.intro.modifiers
 382                 set.add_all modifiers
 383                 return set.to_a
 384         end
 385
 386         fun tpl_modifiers: Template do
 387                 var tpl = new Template
 388                 for modifier in modifiers do
 389                         if modifier == "public" then continue
 390                         tpl.add "{modifier} "
 391                 end
 392                 return tpl
 393         end
 394
 395         redef fun tpl_list_item do
 396                 var lnk = new Template
 397                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 398                 lnk.add tpl_link
 399                 if mdoc != null then
 400                         lnk.add ": "
 401                         lnk.add mdoc.short_markdown
 402                 else if mclass.intro.mdoc != null then
 403                         lnk.add ": "
 404                         lnk.add mclass.intro.mdoc.short_markdown
 405                 end
 406                 return new TplListItem.with_content(lnk)
 407         end
 408
 409         redef fun tpl_anchor: TplLink do
 410                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 411                 if mdoc != null then
 412                         tpl.title = mdoc.short_comment
 413                 else if mclass.intro.mdoc != null then
 414                         tpl.title = mclass.intro.mdoc.short_comment
 415                 end
 416                 return tpl
 417         end
 418
 419         redef fun tpl_link: TplLink do
 420                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 421                 if mdoc != null then
 422                         tpl.title = mdoc.short_comment
 423                 else if mclass.intro.mdoc != null then
 424                         tpl.title = mclass.intro.mdoc.short_comment
 425                 end
 426                 return tpl
 427         end
 428 end
 429
 430 redef class MProperty
 431         redef fun nitdoc_name do return name.html_escape
 432         redef fun nitdoc_id do return "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}"
 433         redef fun nitdoc_url do return "property_{nitdoc_id}.html"
 434
 435         redef fun mdoc do return intro.mdoc
 436
 437         redef fun tpl_namespace do
 438                 var tpl = new Template
 439                 tpl.add intro_mclassdef.mclass.tpl_namespace
 440                 tpl.add "::<span>"
 441                 tpl.add intro.tpl_link
 442                 tpl.add "</span>"
 443                 return tpl
 444         end
 445
 446         redef fun tpl_declaration do return intro.tpl_declaration
 447
 448         fun tpl_signature: Template do return new Template
 449
 450         redef fun tpl_title do return intro.tpl_title
 451
 452         redef fun tpl_icon do return intro.tpl_icon
 453
 454         redef fun tpl_css_classes do return intro.tpl_css_classes
 455 end
 456
 457 redef class MPropDef
 458         redef fun nitdoc_name do return mproperty.nitdoc_name
 459         redef fun nitdoc_id do return "{mclassdef.nitdoc_id}__{name.to_cmangle}"
 460         redef fun nitdoc_url do return "{mproperty.nitdoc_url}#{nitdoc_id}"
 461
 462         redef fun tpl_anchor: TplLink do
 463                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 464                 if mdoc != null then
 465                         tpl.title = mdoc.short_comment
 466                 else if mproperty.intro.mdoc != null then
 467                         tpl.title = mproperty.intro.mdoc.short_comment
 468                 end
 469                 return tpl
 470         end
 471
 472         redef fun tpl_link: TplLink do
 473                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 474                 if mdoc != null then
 475                         tpl.title = mdoc.short_comment
 476                 else if mproperty.intro.mdoc != null then
 477                         tpl.title = mproperty.intro.mdoc.short_comment
 478                 end
 479                 return tpl
 480         end
 481
 482         redef fun tpl_namespace do
 483                 var tpl = new Template
 484                 tpl.add mclassdef.tpl_namespace
 485                 tpl.add "::"
 486                 tpl.add tpl_link
 487                 return tpl
 488         end
 489
 490         redef fun tpl_article do
 491                 var tpl = new TplArticle(nitdoc_id)
 492                 tpl.summary_title = "in {mclassdef.nitdoc_name}"
 493                 var title = new Template
 494                 title.add "in "
 495                 title.add mclassdef.tpl_link
 496                 tpl.title = title
 497                 tpl.subtitle = tpl_declaration
 498                 if mdoc != null then
 499                         tpl.content = mdoc.tpl_comment
 500                 end
 501                 return tpl
 502         end
 503
 504         redef fun tpl_definition do
 505                 var tpl = new TplDefinition
 506                 tpl.namespace = mclassdef.tpl_namespace
 507                 if mdoc != null then
 508                         tpl.comment = mdoc.tpl_comment
 509                 end
 510                 return tpl
 511         end
 512
 513         redef fun tpl_declaration do
 514                 var tpl = new Template
 515                 tpl.add tpl_modifiers
 516                 tpl.add tpl_link
 517                 tpl.add tpl_signature
 518                 return tpl
 519         end
 520
 521         redef fun tpl_css_classes do
 522                 var set = new HashSet[String]
 523                 if is_intro then set.add "intro"
 524                 set.add_all mproperty.intro.modifiers
 525                 set.add_all modifiers
 526                 return set.to_a
 527         end
 528
 529         fun tpl_modifiers: Template do
 530                 var tpl = new Template
 531                 for modifier in modifiers do
 532                         if modifier == "public" then continue
 533                         tpl.add "{modifier} "
 534                 end
 535                 return tpl
 536         end
 537
 538         fun tpl_signature: Template do return new Template
 539
 540         redef fun tpl_list_item do
 541                 var lnk = new Template
 542                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 543                 var anchor = tpl_link
 544                 anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 545                 lnk.add anchor
 546                 if mdoc != null then
 547                         lnk.add ": "
 548                         lnk.add mdoc.short_markdown
 549                 else if mproperty.intro.mdoc != null then
 550                         lnk.add ": "
 551                         lnk.add mproperty.intro.mdoc.short_markdown
 552                 end
 553                 return new TplListItem.with_content(lnk)
 554         end
 555
 556         fun tpl_inheritance_item: TplListItem do
 557                 var lnk = new Template
 558                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 559                 lnk.add mclassdef.mmodule.tpl_namespace
 560                 lnk.add "::"
 561                 var anchor = mclassdef.tpl_link
 562                 anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 563                 lnk.add anchor
 564                 if mdoc != null then
 565                         lnk.add ": "
 566                         lnk.add mdoc.short_markdown
 567                 end
 568                 var li = new TplListItem.with_content(lnk)
 569                 li.css_classes.add "signature"
 570                 return li
 571         end
 572 end
 573
 574 redef class MMethod
 575         redef fun tpl_signature do
 576                 var tpl = new Template
 577                 var params = new Array[String]
 578                 for param in intro.msignature.mparameters do
 579                         params.add param.name
 580                 end
 581                 if not params.is_empty then
 582                         tpl.add "("
 583                         tpl.add params.join(", ")
 584                         tpl.add ")"
 585                 end
 586                 return tpl
 587         end
 588 end
 589
 590 redef class MMethodDef
 591         redef fun tpl_signature do return msignature.tpl_signature
 592 end
 593
 594 redef class MVirtualTypeProp
 595         redef fun tpl_link do return mvirtualtype.tpl_link
 596         redef fun tpl_signature do return tpl_link
 597 end
 598
 599 redef class MVirtualTypeDef
 600         redef fun tpl_signature do
 601                 var tpl = new Template
 602                 tpl.add ": "
 603                 tpl.add bound.tpl_signature
 604                 return tpl
 605         end
 606 end
 607
 608 redef class MType
 609         fun tpl_signature: Template is abstract
 610 end
 611
 612 redef class MClassType
 613         redef fun tpl_link do return mclass.tpl_link
 614         redef fun tpl_signature do return tpl_link
 615 end
 616
 617 redef class MNullableType
 618         redef fun tpl_signature do
 619                 var tpl = new Template
 620                 tpl.add "nullable "
 621                 tpl.add mtype.tpl_signature
 622                 return tpl
 623         end
 624 end
 625
 626 redef class MGenericType
 627         redef fun tpl_signature do
 628                 var tpl = new Template
 629                 tpl.add tpl_link
 630                 tpl.add "["
 631                 for i in [0..arguments.length[ do
 632                         tpl.add arguments[i].tpl_signature
 633                         if i < arguments.length - 1 then tpl.add ", "
 634                 end
 635                 tpl.add "]"
 636                 return tpl
 637         end
 638 end
 639
 640 redef class MParameterType
 641         redef fun tpl_link do
 642                 return new TplLink.with_title("{mclass.nitdoc_url}#FT_{name}", name, "formal type")
 643         end
 644         redef fun tpl_signature do return tpl_link
 645 end
 646
 647 redef class MVirtualType
 648         redef fun tpl_link do return mproperty.intro.tpl_link
 649         redef fun tpl_signature do return tpl_link
 650 end
 651
 652 redef class MSignature
 653         redef fun tpl_signature do
 654                 var tpl = new Template
 655                 if not mparameters.is_empty then
 656                         tpl.add "("
 657                         for i in [0..mparameters.length[ do
 658                                 tpl.add mparameters[i].tpl_signature
 659                                 if i < mparameters.length - 1 then tpl.add ", "
 660                         end
 661                         tpl.add ")"
 662                 end
 663                 if return_mtype != null then
 664                         tpl.add ": "
 665                         tpl.add return_mtype.tpl_signature
 666                 end
 667                 return tpl
 668         end
 669 end
 670
 671 redef class MParameter
 672         fun tpl_signature: Template do
 673                 var tpl = new Template
 674                 tpl.add "{name}: "
 675                 tpl.add mtype.tpl_signature
 676                 if is_vararg then tpl.add "..."
 677                 return tpl
 678         end
 679 end
 680
 681 redef class ConcernsTree
 682
 683         private var seen = new HashSet[MConcern]
 684
 685         redef fun add(p, e) do
 686                 if seen.has(e) then return
 687                 seen.add e
 688                 super(p, e)
 689         end
 690
 691         fun to_tpl: TplList do
 692                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 693                 for r in roots do
 694                         var li = r.tpl_concern_item
 695                         lst.add_li li
 696                         build_list(r, li)
 697                 end
 698                 return lst
 699         end
 700
 701         private fun build_list(e: MConcern, li: TplListItem) do
 702                 if not sub.has_key(e) then return
 703                 var subs = sub[e]
 704                 var lst = new TplList.with_classes(["list-unstyled", "list-definition"])
 705                 for e2 in subs do
 706                         if e2 isa MGroup and e2.is_root then
 707                                 build_list(e2, li)
 708                         else
 709                                 var sli = e2.tpl_concern_item
 710                                 lst.add_li sli
 711                                 build_list(e2, sli)
 712                         end
 713                 end
 714                 li.append lst
 715         end
 716 end