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                 if mproject != null then
 194                         tpl.add mproject.tpl_namespace
 195                 else if parent != null then
 196                         tpl.add parent.tpl_namespace
 197                 end
 198                 if mproject != null and mproject.root != self then
 199                         tpl.add "::"
 200                         tpl.add tpl_link
 201                 end
 202                 return tpl
 203         end
 204
 205         redef fun tpl_declaration do
 206                 var tpl = new Template
 207                 tpl.add "<span>group "
 208                 tpl.add tpl_link
 209                 tpl.add "</span>"
 210                 return tpl
 211         end
 212
 213         redef fun tpl_definition do
 214                 var tpl = new TplDefinition
 215                 if mdoc != null then
 216                         tpl.comment = mdoc.tpl_comment
 217                 end
 218                 return tpl
 219         end
 220 end
 221
 222 redef class MModule
 223         redef fun nitdoc_name do return name.html_escape
 224
 225         redef fun nitdoc_id do
 226                 if mgroup != null then
 227                         return "{mgroup.nitdoc_id}__{nitdoc_name}"
 228                 end
 229                 return nitdoc_name
 230         end
 231
 232         redef fun nitdoc_url do return "module_{nitdoc_id}.html"
 233
 234         redef fun tpl_declaration do
 235                 var tpl = new Template
 236                 tpl.add "<span>module "
 237                 tpl.add tpl_link
 238                 tpl.add "</span>"
 239                 return tpl
 240         end
 241
 242         redef fun tpl_namespace do
 243                 var tpl = new Template
 244                 if mgroup != null then
 245                         tpl.add mgroup.tpl_namespace
 246                         tpl.add "::"
 247                 end
 248                 tpl.add tpl_link
 249                 return tpl
 250         end
 251
 252         redef fun tpl_definition do
 253                 var tpl = new TplClassDefinition
 254                 if mdoc != null then
 255                         tpl.comment = mdoc.tpl_comment
 256                 end
 257                 return tpl
 258         end
 259
 260         redef fun tpl_css_classes do return ["public"]
 261 end
 262
 263 redef class MClass
 264         redef fun nitdoc_name do return name.html_escape
 265         redef fun nitdoc_id do return "{intro_mmodule.mgroup.mproject}__{name.to_cmangle}"
 266         redef fun nitdoc_url do return "class_{nitdoc_id}.html"
 267         redef fun mdoc do return intro.mdoc
 268
 269         redef fun tpl_declaration do return intro.tpl_declaration
 270
 271         redef fun tpl_namespace do
 272                 var tpl = new Template
 273                 tpl.add intro_mmodule.mgroup.mproject.tpl_namespace
 274                 tpl.add "::<span>"
 275                 tpl.add tpl_link
 276                 tpl.add "</span>"
 277                 return tpl
 278         end
 279
 280         redef fun tpl_title do
 281                 var title = new Template
 282                 title.add tpl_icon
 283                 title.add tpl_link
 284                 title.add tpl_signature
 285                 return title
 286         end
 287
 288         redef fun tpl_icon do return intro.tpl_icon
 289
 290         fun tpl_signature: Template do
 291                 var tpl = new Template
 292                 if arity > 0 then
 293                         tpl.add "["
 294                         tpl.add intro.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                 if not parameter_names.is_empty then
 357                         tpl.add "["
 358                         for i in [0..parameter_names.length[ do
 359                                 tpl.add "{parameter_names[i]}: "
 360                                 tpl.add bound_mtype.arguments[i].tpl_signature
 361                                 if i < parameter_names.length - 1 then tpl.add ", "
 362                         end
 363                         tpl.add "]"
 364                 end
 365                 return tpl
 366         end
 367
 368         redef fun tpl_definition do
 369                 var tpl = new TplClassDefinition
 370                 tpl.namespace = tpl_namespace
 371                 if mdoc != null then
 372                         tpl.comment = mdoc.tpl_comment
 373                 end
 374                 return tpl
 375         end
 376
 377         redef fun tpl_css_classes do
 378                 var set = new HashSet[String]
 379                 if is_intro then set.add "intro"
 380                 set.add_all mclass.intro.modifiers
 381                 set.add_all modifiers
 382                 return set.to_a
 383         end
 384
 385         fun tpl_modifiers: Template do
 386                 var tpl = new Template
 387                 for modifier in modifiers do
 388                         if modifier == "public" then continue
 389                         tpl.add "{modifier} "
 390                 end
 391                 return tpl
 392         end
 393
 394         redef fun tpl_list_item do
 395                 var lnk = new Template
 396                 lnk.add new TplLabel.with_classes(tpl_css_classes)
 397                 lnk.add tpl_link
 398                 if mdoc != null then
 399                         lnk.add ": "
 400                         lnk.add mdoc.short_markdown
 401                 else if mclass.intro.mdoc != null then
 402                         lnk.add ": "
 403                         lnk.add mclass.intro.mdoc.short_markdown
 404                 end
 405                 return new TplListItem.with_content(lnk)
 406         end
 407
 408         redef fun tpl_anchor: TplLink do
 409                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 410                 if mdoc != null then
 411                         tpl.title = mdoc.short_comment
 412                 else if mclass.intro.mdoc != null then
 413                         tpl.title = mclass.intro.mdoc.short_comment
 414                 end
 415                 return tpl
 416         end
 417
 418         redef fun tpl_link: TplLink do
 419                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 420                 if mdoc != null then
 421                         tpl.title = mdoc.short_comment
 422                 else if mclass.intro.mdoc != null then
 423                         tpl.title = mclass.intro.mdoc.short_comment
 424                 end
 425                 return tpl
 426         end
 427 end
 428
 429 redef class MProperty
 430         redef fun nitdoc_name do return name.html_escape
 431         redef fun nitdoc_id do return "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}"
 432         redef fun nitdoc_url do return "property_{nitdoc_id}.html"
 433
 434         redef fun mdoc do return intro.mdoc
 435
 436         redef fun tpl_namespace do
 437                 var tpl = new Template
 438                 tpl.add intro_mclassdef.mclass.tpl_namespace
 439                 tpl.add "::<span>"
 440                 tpl.add intro.tpl_link
 441                 tpl.add "</span>"
 442                 return tpl
 443         end
 444
 445         redef fun tpl_declaration do return intro.tpl_declaration
 446
 447         fun tpl_signature: Template do return new Template
 448
 449         redef fun tpl_title do return intro.tpl_title
 450
 451         redef fun tpl_icon do return intro.tpl_icon
 452
 453         redef fun tpl_css_classes do return intro.tpl_css_classes
 454 end
 455
 456 redef class MPropDef
 457         redef fun nitdoc_name do return mproperty.nitdoc_name
 458         redef fun nitdoc_id do return "{mclassdef.nitdoc_id}__{name.to_cmangle}"
 459         redef fun nitdoc_url do return "{mproperty.nitdoc_url}#{nitdoc_id}"
 460
 461         redef fun tpl_anchor: TplLink do
 462                 var tpl = new TplLink("#{nitdoc_id}", nitdoc_name)
 463                 if mdoc != null then
 464                         tpl.title = mdoc.short_comment
 465                 else if mproperty.intro.mdoc != null then
 466                         tpl.title = mproperty.intro.mdoc.short_comment
 467                 end
 468                 return tpl
 469         end
 470
 471         redef fun tpl_link: TplLink do
 472                 var tpl = new TplLink(nitdoc_url, nitdoc_name)
 473                 if mdoc != null then
 474                         tpl.title = mdoc.short_comment
 475                 else if mproperty.intro.mdoc != null then
 476                         tpl.title = mproperty.intro.mdoc.short_comment
 477                 end
 478                 return tpl
 479         end
 480
 481         redef fun tpl_namespace do
 482                 var tpl = new Template
 483                 tpl.add mclassdef.tpl_namespace
 484                 tpl.add "::"
 485                 tpl.add tpl_link
 486                 return tpl
 487         end
 488
 489         redef fun tpl_article do
 490                 var tpl = new TplArticle(nitdoc_id)
 491                 tpl.summary_title = "in {mclassdef.nitdoc_name}"
 492                 var title = new Template
 493                 title.add "in "
 494                 title.add mclassdef.tpl_link
 495                 tpl.title = title
 496                 tpl.subtitle = tpl_declaration
 497                 if mdoc != null then
 498                         tpl.content = mdoc.tpl_comment
 499                 end
 500                 return tpl
 501         end
 502
 503         redef fun tpl_definition do
 504                 var tpl = new TplDefinition
 505                 tpl.namespace = mclassdef.tpl_namespace
 506                 if mdoc != null then
 507                         tpl.comment = mdoc.tpl_comment
 508                 end
 509                 return tpl
 510         end
 511
 512         redef fun tpl_declaration do
 513                 var tpl = new Template
 514                 tpl.add tpl_modifiers
 515                 tpl.add tpl_link
 516                 tpl.add tpl_signature
 517                 return tpl
 518         end
 519
 520         redef fun tpl_css_classes do
 521                 var set = new HashSet[String]
 522                 if is_intro then set.add "intro"
 523                 set.add_all mproperty.intro.modifiers
 524                 set.add_all modifiers
 525                 return set.to_a
 526         end
 527
 528         fun tpl_modifiers: Template do
 529                 var tpl = new Template
 530                 for modifier in modifiers do
 531                         if modifier == "public" then continue
 532                         tpl.add "{modifier} "
 533                 end
 534                 return tpl
 535         end
 536
 537         fun tpl_signature: Template do return new Template
 538
 539         redef fun tpl_list_item do
 540                 var lnk = new Template
 541                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 542                 var anchor = tpl_link
 543                 anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 544                 lnk.add anchor
 545                 if mdoc != null then
 546                         lnk.add ": "
 547                         lnk.add mdoc.short_markdown
 548                 else if mproperty.intro.mdoc != null then
 549                         lnk.add ": "
 550                         lnk.add mproperty.intro.mdoc.short_markdown
 551                 end
 552                 return new TplListItem.with_content(lnk)
 553         end
 554
 555         fun tpl_inheritance_item: TplListItem do
 556                 var lnk = new Template
 557                 lnk.add new TplLabel.with_classes(tpl_css_classes.to_a)
 558                 lnk.add mclassdef.mmodule.tpl_namespace
 559                 lnk.add "::"
 560                 var anchor = mclassdef.tpl_link
 561                 anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}"
 562                 lnk.add anchor
 563                 if mdoc != null then
 564                         lnk.add ": "
 565                         lnk.add mdoc.short_markdown
 566                 end
 567                 var li = new TplListItem.with_content(lnk)
 568                 li.css_classes.add "signature"
 569                 return li
 570         end
 571 end
 572
 573 redef class MMethod
 574         redef fun tpl_signature do
 575                 var tpl = new Template
 576                 var params = new Array[String]
 577                 for param in intro.msignature.mparameters do
 578                         params.add param.name
 579                 end
 580                 if not params.is_empty then
 581                         tpl.add "("
 582                         tpl.add params.join(", ")
 583                         tpl.add ")"
 584                 end
 585                 return tpl
 586         end
 587 end
 588
 589 redef class MMethodDef
 590         redef fun tpl_signature do return msignature.tpl_signature
 591 end
 592
 593 redef class MVirtualTypeProp
 594         redef fun tpl_link do return mvirtualtype.tpl_link
 595         redef fun tpl_signature do return tpl_link
 596 end
 597
 598 redef class MVirtualTypeDef
 599         redef fun tpl_signature do
 600                 var tpl = new Template
 601                 tpl.add ": "
 602                 tpl.add bound.tpl_signature
 603                 return tpl
 604         end
 605 end
 606
 607 redef class MType
 608         fun tpl_signature: Template is abstract
 609 end
 610
 611 redef class MClassType
 612         redef fun tpl_link do return mclass.tpl_link
 613         redef fun tpl_signature do return tpl_link
 614 end
 615
 616 redef class MNullableType
 617         redef fun tpl_signature do
 618                 var tpl = new Template
 619                 tpl.add "nullable "
 620                 tpl.add mtype.tpl_signature
 621                 return tpl
 622         end
 623 end
 624
 625 redef class MGenericType
 626         redef fun tpl_signature do
 627                 var tpl = new Template
 628                 tpl.add tpl_link
 629                 tpl.add "["
 630                 for i in [0..arguments.length[ do
 631                         tpl.add arguments[i].tpl_signature
 632                         if i < arguments.length - 1 then tpl.add ", "
 633                 end
 634                 tpl.add "]"
 635                 return tpl
 636         end
 637 end
 638
 639 redef class MParameterType
 640         redef fun tpl_link do
 641                 var name = mclass.intro.parameter_names[rank]
 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