src/doc_template.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 # HTML templates used by Nitdoc to generate API documentation
  16 # Pages are assembled using `Template`
  17 module doc_template
  18
  19 import template
  20
  21 # Full Nitdoc page template
  22 class TplNitdocPage
  23         super Template
  24
  25         var head: TplHead writable
  26         var body_attrs = new Array[TagAttribute] # attributes for body tag element
  27         var topmenu: TplTopMenu writable
  28         var sidebar: nullable TplSidebar writable
  29         var content: Streamable writable
  30         var footer: nullable TplFooter writable
  31         var scripts = new Array[TplScript] # js scripts appended to body
  32         init do end
  33
  34         redef fun rendering do
  35                 add "<!DOCTYPE html>"
  36                 add "<head>"
  37                 add head
  38                 add "</head>"
  39                 add "<body"
  40                 for attr in body_attrs do add attr
  41                 add ">"
  42                 add topmenu
  43                 if footer != null then
  44                         add "<div class='page footed'>"
  45                 else
  46                         add "<div class='page'>"
  47                 end
  48                 if sidebar != null then
  49                         add sidebar.as(not null)
  50                 end
  51                 add content
  52                 add "</div>"
  53                 if footer != null then
  54                         add footer.as(not null)
  55                 end
  56                 for script in scripts do
  57                         add script
  58                 end
  59                 add "</body>"
  60                 add "</html>"
  61         end
  62 end
  63
  64 # general layout elements
  65
  66 # <head> tag
  67 class TplHead
  68         super Template
  69
  70         var title: String
  71         var shareurl: String
  72
  73         init(title, shareurl: String) do
  74                 self.title = title
  75                 self.shareurl = shareurl
  76         end
  77
  78         redef fun rendering do
  79                 add """
  80 <meta charset="utf-8"/>
  81 <link rel="stylesheet" href="{{{shareurl}}}/css/main.css" type="text/css"/>
  82 <link rel="stylesheet" href="{{{shareurl}}}/css/Nitdoc.UI.css" type="text/css"/>
  83 <link rel="stylesheet" href="{{{shareurl}}}/css/Nitdoc.QuickSearch.css" type="text/css"/>
  84 <link rel="stylesheet" href="{{{shareurl}}}/css/Nitdoc.GitHub.css" type="text/css"/>
  85 <link rel="stylesheet" href="{{{shareurl}}}/css/Nitdoc.ModalBox.css" type="text/css"/>
  86 <title>{{{title}}}</title>"""
  87         end
  88 end
  89
  90 # Top bar menu
  91 class TplTopMenu
  92         super Template
  93
  94         private var elts = new Array[Streamable]
  95
  96         redef fun rendering do
  97                 add "<header>"
  98                 add "<nav class='main'>"
  99                 if not elts.is_empty then
 100                         add "<ul>"
 101                         for elt in elts do add(elt)
 102                         add "</ul>"
 103                 end
 104                 add "</nav>"
 105                 add "</header>"
 106         end
 107
 108         fun add_elt(href, name: String, is_active: Bool) do
 109                 elts.add(new TplTopMenuElt(href, name, is_active))
 110         end
 111
 112         fun add_raw(content: Streamable) do
 113                 elts.add(content)
 114         end
 115 end
 116
 117 # A topmenu element
 118 private class TplTopMenuElt
 119         super Template
 120
 121         var href: String
 122         var name: String
 123         var is_active: Bool
 124
 125         init(href, name: String, is_active: Bool) do
 126                 self.href = href
 127                 self.name = name
 128                 self.is_active = is_active
 129         end
 130
 131         redef fun rendering do
 132                 if is_active then
 133                         add """<li class="current">{{{name}}}</li>"""
 134                 else
 135                         add """<li><a href="{{{href}}}">{{{name}}}</a></li>"""
 136                 end
 137         end
 138 end
 139
 140 # <footer> element
 141 class TplFooter
 142         super Template
 143
 144         var content: Streamable writable
 145
 146         init(content: Streamable) do self.content = content
 147
 148         redef fun rendering do
 149                 add "<footer>"
 150                 add content
 151                 add "</footer>"
 152         end
 153 end
 154
 155 # sidebar layout
 156
 157 # Sidebar <div>
 158 class TplSidebar
 159         super Template
 160
 161         var boxes = new Array[TplSidebarBox]
 162
 163         redef fun rendering do
 164                 add """"<div class="sidebar">"""
 165                 for box in boxes do add box
 166                 add "</div>"
 167         end
 168 end
 169
 170 # A box that can be added to sidebar
 171 class TplSidebarBox
 172         super Template
 173
 174         var name: String
 175         var elts = new Array[TplSidebarGroup]
 176
 177         init(name: String) do self.name = name
 178
 179         redef fun rendering do
 180                 add """<nav class"properties filterable">"""
 181                 add """    <h3>{{{name}}}</h3>"""
 182                 for elt in elts do add elt
 183                 add "</nav>"
 184         end
 185 end
 186
 187 # A sidebar box group
 188 class TplSidebarGroup
 189         super Template
 190
 191         var name: String
 192         private var elts = new Array[Template]
 193
 194         init(name: String) do self.name = name
 195
 196         redef fun rendering do
 197                 if elts.is_empty then return
 198                 add "<h4>{name}</h4>"
 199                 add "<ul>"
 200                 for elt in elts do add elt
 201                 add "</ul>"
 202         end
 203
 204         fun add_elt(content: Streamable, classes: Array[Streamable]) do
 205                 var tpl = new Template
 206                 tpl.add "<li {classes.join(" ")}>"
 207                 tpl.add content
 208                 tpl.add "</li>"
 209                 elts.add(tpl)
 210         end
 211
 212         fun add_bullet(text, title, content: Streamable, classes: Array[Streamable]) do
 213                 var tpl = new Template
 214                 tpl.add "<span title='{title}'>{text}</span>"
 215                 tpl.add content
 216                 add_elt(tpl, classes)
 217         end
 218 end
 219
 220 # page layouts
 221
 222 # Layout for Overview page
 223 class TplOverviewPage
 224         super Template
 225
 226         var title: nullable Streamable writable
 227         var text: nullable Streamable writable
 228         var graph: nullable TplGraph writable
 229         var modules = new Array[Streamable]
 230         init do end
 231
 232         redef fun rendering do
 233                 add "<div class='content fullpage'>"
 234                 if title != null then add "<h1>{title}</h1>"
 235                 if text != null then add "<article class='overview'>{text}</article>"
 236
 237                 if not modules.is_empty then
 238                         add "<article class='overview'>"
 239                         add "<h2>Modules</h2>"
 240                         add "<ul>"
 241                         for m in modules do
 242                                 add "<li>"
 243                                 add m
 244                                 add "</li>"
 245                         end
 246                         add "</ul>"
 247                 end
 248                 if not graph == null then add graph.as(not null)
 249                 add "</article>"
 250                 add "</div>"
 251         end
 252 end
 253
 254 # Layout for Search page
 255 class TplSearchPage
 256         super Template
 257
 258         var title: nullable Streamable writable
 259         var modules = new Array[Streamable]
 260         var classes = new Array[Streamable]
 261         var props = new Array[Streamable]
 262         init do end
 263
 264         redef fun rendering do
 265                 add "<div class='content fullpage'>"
 266                 if title != null then add "<h1>{title}</h1>"
 267                 if not modules.is_empty then
 268                         add "<article class='modules filterable'>"
 269                         add "<h2>Modules</h2>"
 270                         add "<ul>"
 271                         for m in modules do
 272                                 add "<li>"
 273                                 add m
 274                                 add "</li>"
 275                         end
 276                         add "</ul>"
 277                         add "</article>"
 278                 end
 279                 if not classes.is_empty then
 280                         add "<article class='classes filterable'>"
 281                         add "<h2>Classes</h2>"
 282                         add "<ul>"
 283                         for c in classes do
 284                                 add "<li>"
 285                                 add c
 286                                 add "</li>"
 287                         end
 288                         add "</ul>"
 289                         add "</article>"
 290                 end
 291                 if not props.is_empty then
 292                         add "<article class='properties filterable'>"
 293                         add "<h2>Properties</h2>"
 294                         add "<ul>"
 295                         for p in props do
 296                                 add "<li>"
 297                                 add p
 298                                 add "</li>"
 299                         end
 300                         add "</ul>"
 301                         add "</article>"
 302                 end
 303                 add "</div>"
 304         end
 305 end
 306
 307 # Layout for Module page
 308 class TplModulePage
 309         super Template
 310
 311         var title: nullable Streamable writable
 312         var subtitle: nullable Streamable writable
 313         var definition: nullable TplDefinition writable
 314         var graph: nullable TplGraph writable
 315         var intros = new Array[TplArticle]
 316         var redefs = new Array[TplArticle]
 317         init do end
 318
 319         redef fun rendering do
 320                 add "<div class='content'>"
 321                 if title != null then
 322                         add "<h1>"
 323                         add title.as(not null)
 324                         add "</h1>"
 325                 end
 326                 if subtitle != null then
 327                         add "<div class='subtitle info'>"
 328                         add subtitle.as(not null)
 329                         add "</div>"
 330                 end
 331                 if definition != null then add definition.as(not null)
 332                 if graph != null then add graph.as(not null)
 333                 if not intros.is_empty then
 334                         add "<section class='classes'>"
 335                         add "<h2 class='section-header'>Introduced classes</h2>"
 336                         for intro in intros do add intro
 337                         add "</section>"
 338                 end
 339                 if not redefs.is_empty then
 340                         add "<section class='classes'>"
 341                         add "<h2 class='section-header'>Refined classes</h2>"
 342                         for rdef in redefs do add rdef
 343                         add "</section>"
 344                 end
 345                 add "</div>"
 346         end
 347 end
 348
 349 # Layout for Class page
 350 class TplClassPage
 351         super Template
 352
 353         var title: nullable Streamable writable
 354         var subtitle: nullable Streamable writable
 355         var definition: nullable TplDefinition writable
 356         var graph: nullable TplGraph writable
 357         var concerns: nullable TplConcernList writable
 358         var types = new Array[TplArticle]
 359         var inits = new Array[TplArticle]
 360         var methods = new Array[Streamable]
 361
 362         init do end
 363
 364         redef fun rendering do
 365                 add "<div class='content'>"
 366                 if title != null then
 367                         add "<h1>"
 368                         add title.as(not null)
 369                         add "</h1>"
 370                 end
 371                 if subtitle != null then
 372                         add "<div class='subtitle info'>"
 373                         add subtitle.as(not null)
 374                         add "</div>"
 375                 end
 376                 if definition != null then add definition.as(not null)
 377                 if graph != null then add graph.as(not null)
 378
 379                 if concerns != null then
 380                         add "<section class='concerns'>"
 381                         add "<h2 class='section-header'>Concerns</h2>"
 382                         add concerns.as(not null)
 383                         add "</section>"
 384                 end
 385                 if not types.is_empty then
 386                         add "<section class='types'>"
 387                         add"<h2>Virtual Types</h2>"
 388                         for t in types do add t
 389                         add "</section>"
 390                 end
 391                 if not inits.is_empty then
 392                         add "<section class='constructors'>"
 393                         add"<h2>Constructors</h2>"
 394                         for i in inits do add i
 395                         add "</section>"
 396                 end
 397                 if not methods.is_empty then
 398                         add "<section class='methods'>"
 399                         add"<h2>Methods</h2>"
 400                         for m in methods do add m
 401                         add "</section>"
 402                 end
 403                 add "</div>"
 404         end
 405 end
 406
 407 # layout parts
 408
 409 # A HTML tag attribute
 410 #  `<tag attr="value">`
 411 class TagAttribute
 412         super Template
 413
 414         var name: String
 415         var value: nullable String
 416
 417         init(name: String, value: nullable String) do
 418                 self.name = name
 419                 self.value = value
 420         end
 421
 422         redef fun rendering do
 423                 if value == null then
 424                         add(" {name}")
 425                 else
 426                         add(" {name}=\"{value}\"")
 427                 end
 428         end
 429 end
 430
 431 # JS Script template
 432 class TplScript
 433         super Template
 434
 435         var attrs = new Array[TagAttribute]
 436         var content: nullable Streamable writable
 437
 438         init do
 439                 attrs.add(new TagAttribute("type", "text/javascript"))
 440         end
 441
 442         redef fun rendering do
 443                 add "<script"
 444                 for attr in attrs do add attr
 445                 add ">"
 446                 if content != null then add content.as(not null)
 447                 add "</script>"
 448         end
 449 end
 450
 451 # JS script for Piwik Tracker
 452 class TplPiwikScript
 453         super TplScript
 454
 455         var tracker_url: String
 456         var site_id: String
 457
 458         init(tracker_url, site_id: String) do
 459                 super
 460                 self.tracker_url = tracker_url
 461                 self.site_id = site_id
 462         end
 463
 464         redef fun rendering do
 465                 var tpl = new Template
 466                 tpl.add "<!-- Piwik -->"
 467                 tpl.add "var _paq = _paq || [];"
 468                 tpl.add " _paq.push([\"trackPageView\"]);"
 469                 tpl.add " _paq.push([\"enableLinkTracking\"]);"
 470                 tpl.add "(function() \{"
 471                 tpl.add " var u=((\"https:\" == document.location.protocol) ? \"https\" : \"http\") + \"://{tracker_url}\";"
 472                 tpl.add " _paq.push([\"setTrackerUrl\", u+\"piwik.php\"]);"
 473                 tpl.add " _paq.push([\"setSiteId\", \"{site_id}\"]);"
 474                 tpl.add " var d=document, g=d.createElement(\"script\"), s=d.getElementsByTagName(\"script\")[0]; g.type=\"text/javascript\";"
 475                 tpl.add " g.defer=true; g.async=true; g.src=u+\"piwik.js\"; s.parentNode.insertBefore(g,s);"
 476                 tpl.add "\})();"
 477                 content = tpl
 478                 super
 479         end
 480 end
 481
 482 # Graph image with clicable map
 483 class TplGraph
 484         super Template
 485
 486         var name: String
 487         var alt: String
 488         var map: String
 489
 490         init(name, alt, map: String) do
 491                 self.name = name
 492                 self.alt = alt
 493                 self.map = map
 494         end
 495
 496         redef fun rendering do
 497                 add "<article class='graph'>"
 498                 add "<img src='{name}.png' usemap='#{name}' style='margin:auto' alt='{alt}'/>"
 499                 add "</article>"
 500                 add map
 501         end
 502 end
 503
 504 # A page article (used for module, class, prop description)
 505 class TplArticle
 506         super Template
 507
 508         var id: String writable
 509         var classes = new HashSet[String]
 510         var title: Template writable
 511         var subtitle: Template writable
 512         var content: nullable Template writable
 513
 514         init do end
 515
 516         redef fun rendering do
 517                 add "<article class='{classes.join(" ")}' id='{id}'>"
 518                 add "<h3 class='signature'>"
 519                 add title
 520                 add "</h3>"
 521                 add "<div class='info'>"
 522                 add subtitle
 523                 add "</div>"
 524                 if content != null then
 525                         add content.as(not null)
 526                 end
 527                 add "</article>"
 528         end
 529 end
 530
 531 # A module / class / prop definition
 532 # Contains:
 533 # * namespace of the definition
 534 # * comment
 535 # * link to location
 536 class TplDefinition
 537         super Template
 538
 539         var comment: nullable TplComment writable
 540         var namespace: Streamable writable
 541         var location: nullable Streamable writable
 542         var github_area: nullable TplGithubArea writable
 543
 544         init do end
 545
 546         redef fun rendering do
 547                 add "<div class='description'>"
 548                 if github_area != null then
 549                         add github_area.as(not null)
 550                 end
 551                 if comment == null then
 552                         add "<p class='info inheritance'>"
 553                         add "<span class=\"noComment\">no comment for </span>"
 554                 else
 555                         add comment.as(not null)
 556                         add "<p class='info inheritance'>"
 557                 end
 558                 add "definition in "
 559                 add namespace
 560                 if location != null then
 561                         add " "
 562                         add location.as(not null)
 563                 end
 564                 add "</p>"
 565                 add "</div>"
 566         end
 567 end
 568
 569 # Textarea used by Github comment edition plugin to store comments
 570 class TplGithubArea
 571         super Template
 572
 573         var raw_comment: String writable
 574         var raw_namespace: String writable
 575         var location: String writable
 576
 577         init(raw_comment, raw_namespace, location: String) do
 578                 self.raw_comment = raw_comment
 579                 self.raw_namespace = raw_namespace
 580                 self.location = location
 581         end
 582
 583         redef fun rendering do
 584                 add "<textarea"
 585                 add " class='baseComment'"
 586                 add " data-comment-namespace='{raw_namespace}'"
 587                 add " data-comment-location='{location}'>"
 588                 add raw_comment
 589                 add "</textarea>"
 590         end
 591 end
 592
 593 # Comment box
 594 class TplComment
 595         super Template
 596
 597         var comment: Streamable writable
 598
 599         init(comment: Streamable) do self.comment = comment
 600
 601         redef fun rendering do
 602                 add "<div class='comment'>"
 603                 add comment
 604                 add "</div>"
 605         end
 606 end
 607
 608 # Comment box (for synopsys)
 609 class TplShortComment
 610         super TplComment
 611
 612         redef fun rendering do
 613                 add "<div class='comment'>"
 614                 add "<div class='nitdoc'>"
 615                 add comment
 616                 add "</div>"
 617                 add "</div>"
 618         end
 619 end
 620
 621 # A html link (with optional title)
 622 class TplLink
 623         super Template
 624
 625         var href: String writable
 626         var text: String writable
 627         var title: nullable String writable
 628
 629         init do end
 630
 631         redef fun rendering do
 632                 add "<a href=\""
 633                 add href
 634                 add "\""
 635                 if title != null then
 636                         add " title=\""
 637                         add title.as(not null)
 638                         add "\""
 639                 end
 640                 add ">"
 641                 add text
 642                 add "</a>"
 643         end
 644 end
 645
 646 # Element to display in concerns list
 647 class TplConcernElt
 648         super Template
 649 end
 650
 651 # List of concerns
 652 class TplConcernList
 653         super TplConcernElt
 654
 655         var elts = new Array[TplConcernElt]
 656
 657         redef fun rendering do
 658                 if elts.is_empty then return
 659                 add "<ul>"
 660                 for elt in elts do
 661                         add elt
 662                 end
 663                 add "</ul>"
 664         end
 665 end
 666
 667 # Element of a list of concerns
 668 class TplConcernListElt
 669         super TplConcernElt
 670
 671         var anchor: String writable
 672         var name: String writable
 673         var comment: nullable String writable
 674
 675         init do end
 676
 677         redef fun rendering do
 678                 add "<li>"
 679                 add "<a href=\"{anchor}\">{name}</a>"
 680                 if comment != null then
 681                         add ": {comment.as(not null)}"
 682                 end
 683                 add "</li>"
 684         end
 685 end
 686
 687 # Section for topconcern
 688 class TplTopConcern
 689         super Template
 690
 691         var anchor: String writable
 692         var concern: TplLink writable
 693
 694         init do end
 695
 696         redef fun rendering do
 697                 add "<a id=\"{anchor}\"></a>"
 698                 add "<h3 class=\"concern-toplevel\">Methods refined in "
 699                 add concern
 700                 add "</h3>"
 701         end
 702 end
 703
 704 # Section for subconcern
 705 class TplConcern
 706         super Template
 707
 708         var anchor: String writable
 709         var concern: TplLink writable
 710         var comment: nullable String writable
 711
 712         init do end
 713
 714         redef fun rendering do
 715                 add "<a id=\"{anchor}\"></a>"
 716                 add "<p class=\"concern-doc\">"
 717                 add concern
 718                 if comment != null then
 719                         add ": "
 720                         add comment.as(not null)
 721                 end
 722                 add "</p>"
 723         end
 724 end