src/doc/doc_pages.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 page generation
  16 module doc_pages
  17
  18 import doc_model
  19
  20 # The NitdocContext contains all the knowledge used for doc generation
  21 class NitdocContext
  22         private var opt_dir = new OptionString("output directory", "-d", "--dir")
  23         private var opt_source = new OptionString("link for source (%f for filename, %l for first line, %L for last line)", "--source")
  24         private var opt_sharedir = new OptionString("directory containing nitdoc assets", "--sharedir")
  25         private var opt_shareurl = new OptionString("use shareurl instead of copy shared files", "--shareurl")
  26         private var opt_nodot = new OptionBool("do not generate graphes with graphviz", "--no-dot")
  27         private var opt_private = new OptionBool("also generate private API", "--private")
  28
  29         private var opt_custom_title = new OptionString("custom title for homepage", "--custom-title")
  30         private var opt_custom_brand = new OptionString("custom link to external site", "--custom-brand")
  31         private var opt_custom_intro = new OptionString("custom intro text for homepage", "--custom-overview-text")
  32         private var opt_custom_footer = new OptionString("custom footer text", "--custom-footer-text")
  33
  34         private var opt_github_upstream = new OptionString("Git branch where edited commits will be pulled into (ex: user:repo:branch)", "--github-upstream")
  35         private var opt_github_base_sha1 = new OptionString("Git sha1 of base commit used to create pull request", "--github-base-sha1")
  36         private var opt_github_gitdir = new OptionString("Git working directory used to resolve path name (ex: /home/me/myproject/)", "--github-gitdir")
  37
  38         private var opt_piwik_tracker = new OptionString("Piwik tracker URL (ex: nitlanguage.org/piwik/)", "--piwik-tracker")
  39         private var opt_piwik_site_id = new OptionString("Piwik site ID", "--piwik-site-id")
  40
  41         private var toolcontext = new ToolContext
  42         private var mbuilder: ModelBuilder
  43         private var mainmodule: MModule
  44         private var output_dir: String
  45         private var min_visibility: MVisibility
  46
  47         init do
  48                 var opts = toolcontext.option_context
  49                 opts.add_option(opt_dir, opt_source, opt_sharedir, opt_shareurl, opt_nodot, opt_private)
  50                 opts.add_option(opt_custom_title, opt_custom_footer, opt_custom_intro, opt_custom_brand)
  51                 opts.add_option(opt_github_upstream, opt_github_base_sha1, opt_github_gitdir)
  52                 opts.add_option(opt_piwik_tracker, opt_piwik_site_id)
  53
  54                 var tpl = new Template
  55                 tpl.add "Usage: nitdoc [OPTION]... <file.nit>...\n"
  56                 tpl.add "Generates HTML pages of API documentation from Nit source files."
  57                 toolcontext.tooldescription = tpl.write_to_string
  58                 toolcontext.process_options(args)
  59
  60                 self.process_options
  61                 self.parse(toolcontext.option_context.rest)
  62         end
  63
  64         private fun process_options do
  65                 if opt_private.value then
  66                         min_visibility = none_visibility
  67                 else
  68                         min_visibility = protected_visibility
  69                 end
  70                 var gh_upstream = opt_github_upstream.value
  71                 var gh_base_sha = opt_github_base_sha1.value
  72                 var gh_gitdir = opt_github_gitdir.value
  73                 if not gh_upstream == null or not gh_base_sha == null or not gh_gitdir == null then
  74                         if gh_upstream == null or gh_base_sha == null or gh_gitdir == null then
  75                                 print "Error: Options {opt_github_upstream.names.first}, {opt_github_base_sha1.names.first} and {opt_github_gitdir.names.first} are required to enable the GitHub plugin"
  76                                 abort
  77                         end
  78                 end
  79         end
  80
  81         private fun parse(arguments: Array[String]) do
  82                 var model = new Model
  83                 mbuilder = new ModelBuilder(model, toolcontext)
  84                 var mmodules = mbuilder.parse(arguments)
  85                 if mmodules.is_empty then return
  86                 mbuilder.run_phases
  87                 if mmodules.length == 1 then
  88                         mainmodule = mmodules.first
  89                 else
  90                         mainmodule = new MModule(model, null, "<main>", new Location(null, 0, 0, 0, 0))
  91                         mainmodule.is_fictive = true
  92                         mainmodule.set_imported_mmodules(mmodules)
  93                 end
  94         end
  95
  96         fun generate_nitdoc do
  97                 init_output_dir
  98                 overview
  99                 search
 100                 modules
 101                 classes
 102                 quicksearch_list
 103         end
 104
 105         private fun init_output_dir do
 106                 # location output dir
 107                 var output_dir = opt_dir.value
 108                 if output_dir == null then
 109                         output_dir = "doc"
 110                 end
 111                 self.output_dir = output_dir
 112                 # create destination dir if it's necessary
 113                 if not output_dir.file_exists then output_dir.mkdir
 114                 # locate share dir
 115                 var sharedir = opt_sharedir.value
 116                 if sharedir == null then
 117                         var dir = toolcontext.nit_dir
 118                         if dir == null then
 119                                 print "Error: Cannot locate nitdoc share files. Uses --sharedir or envvar NIT_DIR"
 120                                 abort
 121                         end
 122                         sharedir = "{dir}/share/nitdoc"
 123                         if not sharedir.file_exists then
 124                                 print "Error: Cannot locate nitdoc share files. Uses --sharedir or envvar NIT_DIR"
 125                                 abort
 126                         end
 127                 end
 128                 # copy shared files
 129                 if opt_shareurl.value == null then
 130                         sys.system("cp -r {sharedir.to_s}/* {output_dir.to_s}/")
 131                 else
 132                         sys.system("cp -r {sharedir.to_s}/resources/ {output_dir.to_s}/resources/")
 133                 end
 134
 135         end
 136
 137         private fun overview do
 138                 var overviewpage = new NitdocOverview(self)
 139                 overviewpage.render.write_to_file("{output_dir.to_s}/index.html")
 140         end
 141
 142         private fun search do
 143                 var searchpage = new NitdocSearch(self)
 144                 searchpage.render.write_to_file("{output_dir.to_s}/search.html")
 145         end
 146
 147         private fun modules do
 148                 for mmodule in mbuilder.model.mmodules do
 149                         if mmodule.name == "<main>" then continue
 150                         var modulepage = new NitdocModule(mmodule, self)
 151                         modulepage.render.write_to_file("{output_dir.to_s}/{mmodule.nitdoc_url}")
 152                 end
 153         end
 154
 155         private fun classes do
 156                 for mclass in mbuilder.model.mclasses do
 157                         var classpage = new NitdocClass(mclass, self)
 158                         classpage.render.write_to_file("{output_dir.to_s}/{mclass.nitdoc_url}")
 159                 end
 160         end
 161
 162         private fun quicksearch_list do
 163                 var quicksearch = new QuickSearch(self)
 164                 quicksearch.render.write_to_file("{output_dir.to_s}/quicksearch-list.js")
 165         end
 166 end
 167
 168 # Nitdoc QuickSearch list generator
 169 #
 170 # Create a JSON object containing links to:
 171 #  * modules
 172 #  * mclasses
 173 #  * mpropdefs
 174 # All entities are grouped by name to make the research easier.
 175 class QuickSearch
 176
 177         private var mmodules = new HashSet[MModule]
 178         private var mclasses = new HashSet[MClass]
 179         private var mpropdefs = new HashMap[String, Set[MPropDef]]
 180
 181         init(ctx: NitdocContext) do
 182                 for mmodule in ctx.mbuilder.model.mmodules do
 183                         if mmodule.name == "<main>" then continue
 184                         mmodules.add mmodule
 185                 end
 186                 for mclass in ctx.mbuilder.model.mclasses do
 187                         if mclass.visibility < ctx.min_visibility then continue
 188                         mclasses.add mclass
 189                 end
 190                 for mproperty in ctx.mbuilder.model.mproperties do
 191                         if mproperty.visibility < ctx.min_visibility then continue
 192                         if mproperty isa MAttribute then continue
 193                         if not mpropdefs.has_key(mproperty.name) then
 194                                 mpropdefs[mproperty.name] = new HashSet[MPropDef]
 195                         end
 196                         mpropdefs[mproperty.name].add_all(mproperty.mpropdefs)
 197                 end
 198         end
 199
 200         fun render: Template do
 201                 var tpl = new Template
 202                 tpl.add "var nitdocQuickSearchRawList=\{ "
 203                 for mmodule in mmodules do
 204                         tpl.add "\"{mmodule.name}\":["
 205                         tpl.add "\{txt:\"{mmodule.full_name}\",url:\"{mmodule.nitdoc_url}\"\},"
 206                         tpl.add "],"
 207                 end
 208                 for mclass in mclasses do
 209                         var full_name = mclass.intro.mmodule.full_name
 210                         tpl.add "\"{mclass.name}\":["
 211                         tpl.add "\{txt:\"{full_name}\",url:\"{mclass.nitdoc_url}\"\},"
 212                         tpl.add "],"
 213                 end
 214                 for mproperty, mprops in mpropdefs do
 215                         tpl.add "\"{mproperty}\":["
 216                         for mpropdef in mprops do
 217                                 var full_name = mpropdef.mclassdef.mclass.full_name
 218                                 tpl.add "\{txt:\"{full_name}\",url:\"{mpropdef.nitdoc_url}\"\},"
 219                         end
 220                         tpl.add "],"
 221                 end
 222                 tpl.add " \};"
 223                 return tpl
 224         end
 225 end
 226
 227 # Nitdoc base page
 228 # Define page structure and properties
 229 abstract class NitdocPage
 230
 231         private var ctx: NitdocContext
 232         private var model: Model
 233         private var name_sorter = new MEntityNameSorter
 234
 235         init(ctx: NitdocContext) do
 236                 self.ctx = ctx
 237                 self.model = ctx.mbuilder.model
 238         end
 239
 240         # Render the page as a html template
 241         fun render: Template do
 242                 var shareurl = "."
 243                 if ctx.opt_shareurl.value != null then
 244                         shareurl = ctx.opt_shareurl.value.as(not null)
 245                 end
 246
 247                 # build page
 248                 var tpl = tpl_page
 249                 tpl.title = tpl_title
 250                 tpl.shareurl = shareurl
 251                 tpl.topmenu = tpl_topmenu
 252                 tpl_content
 253                 tpl.footer = ctx.opt_custom_footer.value
 254                 tpl.body_attrs.add(new TagAttribute("data-bootstrap-share", shareurl))
 255                 tpl.sidebar = tpl_sidebar
 256
 257                 # piwik tracking
 258                 var tracker_url = ctx.opt_piwik_tracker.value
 259                 var site_id = ctx.opt_piwik_site_id.value
 260                 if tracker_url != null and site_id != null then
 261                         tpl.scripts.add new TplPiwikScript(tracker_url, site_id)
 262                 end
 263                 return tpl
 264         end
 265
 266         # Build page template
 267         fun tpl_page: TplPage is abstract
 268
 269         # Build page sidebar if any
 270         fun tpl_sidebar: nullable TplSidebar do return null
 271
 272         # Build page title string
 273         fun tpl_title: String do
 274                 if ctx.opt_custom_title.value != null then
 275                         return ctx.opt_custom_title.value.to_s
 276                 end
 277                 return "Nitdoc"
 278         end
 279
 280         # Build top menu template
 281         fun tpl_topmenu: TplTopMenu do
 282                 var topmenu = new TplTopMenu
 283                 var brand = ctx.opt_custom_brand.value
 284                 if brand != null then
 285                         var tpl = new Template
 286                         tpl.add "<span class='navbar-brand'>"
 287                         tpl.add brand
 288                         tpl.add "</span>"
 289                         topmenu.brand = tpl
 290                 end
 291                 return topmenu
 292         end
 293
 294         # Build page content template
 295         fun tpl_content is abstract
 296
 297         # Clickable graphviz image using dot format
 298         # return null if no graph for this page
 299         fun tpl_graph(dot: FlatBuffer, name: String, title: String): nullable TplArticle do
 300                 if ctx.opt_nodot.value then return null
 301                 var output_dir = ctx.output_dir
 302                 var file = new OFStream.open("{output_dir}/{name}.dot")
 303                 file.write(dot)
 304                 file.close
 305                 sys.system("\{ test -f {output_dir}/{name}.png && test -f {output_dir}/{name}.s.dot && diff {output_dir}/{name}.dot {output_dir}/{name}.s.dot >/dev/null 2>&1 ; \} || \{ cp {output_dir}/{name}.dot {output_dir}/{name}.s.dot && dot -Tpng -o{output_dir}/{name}.png -Tcmapx -o{output_dir}/{name}.map {output_dir}/{name}.s.dot ; \}")
 306                 var fmap = new IFStream.open("{output_dir}/{name}.map")
 307                 var map = fmap.read_all
 308                 fmap.close
 309
 310                 var article = new TplArticle.with_title("graph", title)
 311                 var content = new Template
 312                 content.add "<img src='{name}.png' usemap='#{name}' style='margin:auto' alt='{title}'/>"
 313                 content.add map
 314                 article.content = content
 315                 return article
 316         end
 317
 318         # A (source) link template for a given location
 319         fun tpl_showsource(location: nullable Location): nullable String
 320         do
 321                 if location == null then return null
 322                 var source = ctx.opt_source.value
 323                 if source == null then return "({location.file.filename.simplify_path})"
 324                 # THIS IS JUST UGLY ! (but there is no replace yet)
 325                 var x = source.split_with("%f")
 326                 source = x.join(location.file.filename.simplify_path)
 327                 x = source.split_with("%l")
 328                 source = x.join(location.line_start.to_s)
 329                 x = source.split_with("%L")
 330                 source = x.join(location.line_end.to_s)
 331                 source = source.simplify_path
 332                 return " (<a target='_blank' title='Show source' href=\"{source.to_s}\">source</a>)"
 333         end
 334
 335         # MClassDef description template
 336         fun tpl_mclass_article(mclass: MClass, mclassdefs: Array[MClassDef]): TplArticle do
 337                 var article = new TplArticle(mclass.nitdoc_anchor)
 338                 var title = new Template
 339                 var icon = new TplIcon.with_icon("tag")
 340                 icon.css_classes.add_all(mclass.intro.tpl_css_classes)
 341                 title.add icon
 342                 title.add mclass.tpl_link
 343                 title.add mclass.intro.tpl_signature
 344                 article.title = title
 345                 article.title_classes.add "signature"
 346                 article.subtitle = mclass.tpl_declaration
 347                 article.summary_title = "{mclass.nitdoc_name}{mclass.tpl_signature.write_to_string}"
 348                 #article.subtitle = new Template
 349                 #article.subtitle.add mprop.intro.tpl_modifiers
 350                 #article.subtitle.add mprop.intro.tpl_namespace
 351                 var content = new Template
 352
 353                 if not mclassdefs.has(mclass.intro) then
 354                         # add intro synopsys
 355                         var intro = mclass.intro
 356                         var location = intro.location
 357                         var sourcelink = tpl_showsource(location)
 358                         var intro_def = intro.tpl_definition
 359                         intro_def.location = sourcelink
 360                         content.add intro_def
 361                 end
 362                 ctx.mainmodule.linearize_mclassdefs(mclassdefs)
 363                 for mclassdef in mclassdefs do
 364                         # add mclassdef full description
 365                         var location = mclassdef.location
 366                         var sourcelink = tpl_showsource(location)
 367                         var prop_def = mclassdef.tpl_definition.as(TplClassDefinition)
 368                         prop_def.location = sourcelink
 369                         for mpropdef in mclassdef.mpropdefs do
 370                                 var intro = mpropdef.mproperty.intro
 371                                 if mpropdef isa MAttributeDef then continue
 372                                 if mpropdef.mproperty.visibility < ctx.min_visibility then continue
 373
 374                                 var lnk = new Template
 375                                 lnk.add new TplLabel.with_classes(mpropdef.tpl_css_classes.to_a)
 376                                 lnk.add mpropdef.tpl_link
 377                                 if intro.mdoc != null then
 378                                         lnk.add ": "
 379                                         lnk.add intro.mdoc.short_comment
 380                                 end
 381                                 if mpropdef.is_intro then
 382                                         prop_def.intros.add new TplListItem.with_content(lnk)
 383                                 else
 384                                         prop_def.redefs.add new TplListItem.with_content(lnk)
 385                                 end
 386                         end
 387                         content.add prop_def
 388                 end
 389                 article.content = content
 390                 return article
 391         end
 392
 393         # MProp description template
 394         fun tpl_mprop_article(mprop: MProperty, mpropdefs: Array[MPropDef]): TplArticle do
 395                 var article = new TplArticle(mprop.intro.nitdoc_anchor)
 396                 var icon = new TplIcon.with_icon("tag")
 397                 icon.css_classes.add_all(mprop.intro.tpl_css_classes)
 398                 var title = new Template
 399                 title.add icon
 400                 title.add mprop.nitdoc_name
 401                 title.add mprop.intro.tpl_signature
 402                 article.title = title
 403                 article.title_classes.add "signature"
 404                 article.subtitle = mprop.tpl_declaration
 405                 article.summary_title = mprop.nitdoc_name
 406                 #article.subtitle = new Template
 407                 #article.subtitle.add mprop.intro.tpl_modifiers
 408                 #article.subtitle.add mprop.intro.tpl_namespace
 409                 var content = new Template
 410
 411                 if not mpropdefs.has(mprop.intro) then
 412                         # add intro synopsys
 413                         var intro = mprop.intro
 414                         var location = intro.location
 415                         var sourcelink = tpl_showsource(location)
 416                         var intro_def = intro.tpl_definition
 417                         intro_def.location = sourcelink
 418                         content.add intro_def
 419                 end
 420
 421                 ctx.mainmodule.linearize_mpropdefs(mpropdefs)
 422                 for mpropdef in mpropdefs do
 423                         # add mpropdef description
 424                         var location = mpropdef.location
 425                         var sourcelink = tpl_showsource(location)
 426                         var prop_def = mpropdef.tpl_definition
 427                         prop_def.location = sourcelink
 428                         content.add prop_def
 429                 end
 430                 article.content = content
 431                 return article
 432         end
 433 end
 434
 435 # The overview page
 436 # Display a list of modules contained in program
 437 class NitdocOverview
 438         super NitdocPage
 439
 440         init(ctx: NitdocContext) do super(ctx)
 441
 442         private var page = new TplPage
 443         redef fun tpl_page do return page
 444
 445         private var sidebar = new TplSidebar
 446         redef fun tpl_sidebar do return sidebar
 447
 448         redef fun tpl_title do
 449                 if ctx.opt_custom_title.value != null then
 450                         return ctx.opt_custom_title.value.to_s
 451                 else
 452                         return "Overview"
 453                 end
 454         end
 455
 456         redef fun tpl_topmenu do
 457                 var topmenu = super
 458                 topmenu.add_item(new TplLink("#", "Overview"), true)
 459                 topmenu.add_item(new TplLink("search.html", "Index"), false)
 460                 return topmenu
 461         end
 462
 463         # intro text
 464         private fun tpl_intro: TplSection do
 465                 var section = new TplSection.with_title("overview", tpl_title)
 466                 var article = new TplArticle("intro")
 467                 if ctx.opt_custom_intro.value != null then
 468                         article.content = ctx.opt_custom_intro.value.to_s
 469                 end
 470                 section.add_child article
 471                 return section
 472         end
 473
 474         # projects list
 475         private fun tpl_projects(section: TplSection) do
 476                 # Projects list
 477                 var ssection = new TplSection.with_title("projects", "Projects")
 478                 for mproject in model.mprojects do
 479                         ssection.add_child mproject.tpl_article
 480                 end
 481                 section.add_child ssection
 482         end
 483
 484         redef fun tpl_content do
 485                 var top = tpl_intro
 486                 tpl_projects(top)
 487                 tpl_page.add_section top
 488         end
 489 end
 490
 491 # The search page
 492 # Display a list of modules, classes and properties
 493 class NitdocSearch
 494         super NitdocPage
 495
 496         init(ctx: NitdocContext) do super(ctx)
 497
 498         private var page = new TplPage
 499         redef fun tpl_page do return page
 500
 501         redef fun tpl_title do return "Index"
 502
 503         redef fun tpl_topmenu do
 504                 var topmenu = super
 505                 topmenu.add_item(new TplLink("index.html", "Overview"), false)
 506                 topmenu.add_item(new TplLink("#", "Index"), true)
 507                 return topmenu
 508         end
 509
 510         redef fun tpl_content do
 511                 var tpl = new TplSearchPage("search_all")
 512                 var section = new TplSection("search")
 513                 # title
 514                 tpl.title = "Index"
 515                 # modules list
 516                 for mmodule in modules_list do
 517                         tpl.modules.add mmodule.tpl_link
 518                 end
 519                 # classes list
 520                 for mclass in classes_list do
 521                         tpl.classes.add mclass.tpl_link
 522                 end
 523                 # properties list
 524                 for mproperty in mprops_list do
 525                         var m = new Template
 526                         m.add mproperty.intro.tpl_link
 527                         m.add " ("
 528                         m.add mproperty.intro.mclassdef.mclass.tpl_link
 529                         m.add ")"
 530                         tpl.props.add m
 531                 end
 532                 section.add_child tpl
 533                 tpl_page.add_section section
 534         end
 535
 536         # Extract mmodule list to display (sorted by name)
 537         private fun modules_list: Array[MModule] do
 538                 var sorted = new Array[MModule]
 539                 for mmodule in ctx.mbuilder.model.mmodule_importation_hierarchy do
 540                         if mmodule.name == "<main>" then continue
 541                         sorted.add mmodule
 542                 end
 543                 name_sorter.sort(sorted)
 544                 return sorted
 545         end
 546
 547         # Extract mclass list to display (sorted by name)
 548         private fun classes_list: Array[MClass] do
 549                 var sorted = new Array[MClass]
 550                 for mclass in ctx.mbuilder.model.mclasses do
 551                         if mclass.visibility < ctx.min_visibility then continue
 552                         sorted.add mclass
 553                 end
 554                 name_sorter.sort(sorted)
 555                 return sorted
 556         end
 557
 558         # Extract mproperty list to display (sorted by name)
 559         private fun mprops_list: Array[MProperty] do
 560                 var sorted = new Array[MProperty]
 561                 for mproperty in ctx.mbuilder.model.mproperties do
 562                         if mproperty.visibility < ctx.min_visibility then continue
 563                         if mproperty isa MAttribute then continue
 564                         sorted.add mproperty
 565                 end
 566                 name_sorter.sort(sorted)
 567                 return sorted
 568         end
 569 end
 570
 571 # A module page
 572 # Display the list of introduced and redefined classes in module
 573 class NitdocModule
 574         super NitdocPage
 575
 576         private var mmodule: MModule
 577
 578         init(mmodule: MModule, ctx: NitdocContext) do
 579                 self.mmodule = mmodule
 580                 super(ctx)
 581         end
 582
 583         private var page = new TplPage
 584         redef fun tpl_page do return page
 585
 586         private var sidebar = new TplSidebar
 587         redef fun tpl_sidebar do return sidebar
 588
 589         redef fun tpl_title do return "{mmodule.nitdoc_name}"
 590
 591         redef fun tpl_topmenu do
 592                 var topmenu = super
 593                 topmenu.add_item(new TplLink("index.html", "Overview"), false)
 594                 topmenu.add_item(new TplLink("#", "{mmodule.nitdoc_name}"), true)
 595                 topmenu.add_item(new TplLink("search.html", "Index"), false)
 596                 return topmenu
 597         end
 598
 599         # intro text
 600         private fun tpl_intro: TplSection do
 601                 var section = new TplSection.with_title(mmodule.nitdoc_anchor, tpl_title)
 602                 section.subtitle = mmodule.tpl_declaration
 603
 604                 var article = new TplArticle("intro")
 605                 var def = mmodule.tpl_definition
 606                 var location = mmodule.location
 607                 def.location = tpl_showsource(location)
 608                 article.content = def
 609                 section.add_child article
 610                 return section
 611         end
 612
 613         # inheritance section
 614         private fun tpl_inheritance(parent: TplSection) do
 615                 # Extract relevent modules
 616                 var nested = mmodule.in_nesting.direct_greaters.to_a
 617                 var imports = mmodule.in_importation.greaters
 618                 if imports.length > 10 then imports = mmodule.in_importation.direct_greaters
 619                 var clients = mmodule.in_importation.smallers
 620                 if clients.length > 10 then clients = mmodule.in_importation.direct_smallers
 621
 622                 # Display lists
 623                 var section = new TplSection.with_title("inheritance", "Inheritance")
 624
 625                 # Graph
 626                 var mmodules = new HashSet[MModule]
 627                 mmodules.add_all nested
 628                 mmodules.add_all imports
 629                 if clients.length < 10 then mmodules.add_all clients
 630                 mmodules.add mmodule
 631                 var graph = tpl_dot(mmodules)
 632                 if graph != null then section.add_child graph
 633
 634                 # nested modules
 635                 if not nested.is_empty then
 636                         var lst = nested.to_a
 637                         name_sorter.sort lst
 638                         section.add_child tpl_list("nesting", "Nested modules", lst)
 639                 end
 640
 641                 # Imports
 642                 var lst = new Array[MModule]
 643                 for dep in imports do
 644                         if dep.is_fictive then continue
 645                         if dep == mmodule then continue
 646                         lst.add(dep)
 647                 end
 648                 if not lst.is_empty then
 649                         name_sorter.sort lst
 650                         section.add_child tpl_list("imports", "Imports", lst)
 651                 end
 652
 653                 # Clients
 654                 lst = new Array[MModule]
 655                 for dep in clients do
 656                         if dep.is_fictive then continue
 657                         if dep == mmodule then continue
 658                         lst.add(dep)
 659                 end
 660                 if not lst.is_empty then
 661                         name_sorter.sort lst
 662                         section.add_child tpl_list("clients", "Clients", lst)
 663                 end
 664
 665                 parent.add_child section
 666         end
 667
 668         private fun tpl_list(id: String, title: String, mmodules: Array[MModule]): TplArticle do
 669                 var article = new TplArticle.with_title(id, title)
 670                 var list = new TplList.with_classes(["list-unstyled", "list-definition"])
 671                 for mmodule in mmodules do list.elts.add mmodule.tpl_list_item
 672                 article.content = list
 673                 return article
 674         end
 675
 676         private fun tpl_mclasses(parent: TplSection) do
 677                 var mclassdefs = new HashSet[MClassDef]
 678                 mclassdefs.add_all mmodule.in_nesting_intro_mclassdefs(ctx.min_visibility)
 679                 mclassdefs.add_all mmodule.in_nesting_redef_mclassdefs(ctx.min_visibility)
 680                 var mclasses2mdefs = sort_by_mclass(mclassdefs)
 681                 var sorted_mclasses = mclasses2mdefs.keys.to_a
 682                 name_sorter.sort sorted_mclasses
 683
 684                 # intros
 685                 var section = new TplSection.with_title("intros", "Introductions")
 686                 var intros = mmodule.in_nesting_intro_mclasses(ctx.min_visibility)
 687                 var sorted_intros = intros.to_a
 688                 name_sorter.sort(sorted_intros)
 689                 for mclass in sorted_intros do
 690                         if not mclasses2mdefs.has_key(mclass) then continue
 691                         section.add_child tpl_mclass_article(mclass, mclasses2mdefs[mclass].to_a)
 692                 end
 693                 parent.add_child section
 694
 695                 # redefs
 696                 section = new TplSection.with_title("redefs", "Refinements")
 697                 var redefs = mmodule.in_nesting_redef_mclasses(ctx.min_visibility).to_a
 698                 name_sorter.sort(redefs)
 699                 for mclass in redefs do
 700                         if intros.has(mclass) then continue
 701                         if not mclasses2mdefs.has_key(mclass) then continue
 702                         section.add_child tpl_mclass_article(mclass, mclasses2mdefs[mclass].to_a)
 703                 end
 704                 parent.add_child section
 705         end
 706
 707         redef fun tpl_content do
 708                 var top = tpl_intro
 709                 tpl_inheritance(top)
 710                 tpl_mclasses(top)
 711                 tpl_page.add_section top
 712         end
 713
 714         # Genrate dot hierarchy for class inheritance
 715         fun tpl_dot(mmodules: Collection[MModule]): nullable TplArticle do
 716                 var poset = new POSet[MModule]
 717                 for mmodule in mmodules do
 718                         if mmodule.is_fictive then continue
 719                         poset.add_node mmodule
 720                         for omodule in mmodules do
 721                                 if mmodule.is_fictive then continue
 722                                 poset.add_node mmodule
 723                                 if mmodule.in_importation < omodule then
 724                                         poset.add_edge(mmodule, omodule)
 725                                 end
 726                         end
 727                 end
 728                 # build graph
 729                 var op = new FlatBuffer
 730                 var name = "dep_{mmodule.name}"
 731                 op.append("digraph {name} \{ rankdir=BT; node[shape=none,margin=0,width=0,height=0,fontsize=10]; edge[dir=none,color=gray]; ranksep=0.2; nodesep=0.1;\n")
 732                 for mmodule in poset do
 733                         if mmodule == self.mmodule then
 734                                 op.append("\"{mmodule.name}\"[shape=box,margin=0.03];\n")
 735                         else
 736                                 op.append("\"{mmodule.name}\"[URL=\"{mmodule.nitdoc_url}\"];\n")
 737                         end
 738                         for omodule in poset[mmodule].direct_greaters do
 739                                 op.append("\"{mmodule.name}\"->\"{omodule.name}\";\n")
 740                         end
 741                 end
 742                 op.append("\}\n")
 743                 return tpl_graph(op, name, "Dependency graph")
 744         end
 745
 746         private fun sort_by_mclass(mclassdefs: Collection[MClassDef]): Map[MClass, Set[MClassDef]] do
 747                 var map = new HashMap[MClass, Set[MClassDef]]
 748                 for mclassdef in mclassdefs do
 749                         var mclass = mclassdef.mclass
 750                         if not map.has_key(mclass) then map[mclass] = new HashSet[MClassDef]
 751                         map[mclass].add mclassdef
 752                 end
 753                 return map
 754         end
 755 end
 756
 757 # A class page
 758 # Display a list properties defined or redefined for this class
 759 class NitdocClass
 760         super NitdocPage
 761
 762         private var mclass: MClass
 763         private var mprops2mdefs: Map[MProperty, Set[MPropDef]]
 764
 765         init(mclass: MClass, ctx: NitdocContext) do
 766                 self.mclass = mclass
 767                 super(ctx)
 768                 var mpropdefs = new HashSet[MPropDef]
 769                 mpropdefs.add_all mclass.intro_mpropdefs(ctx.min_visibility)
 770                 mpropdefs.add_all mclass.redef_mpropdefs(ctx.min_visibility)
 771                 mprops2mdefs = sort_by_mproperty(mpropdefs)
 772         end
 773
 774         private var page = new TplPage
 775         redef fun tpl_page do return page
 776
 777         private var sidebar = new TplSidebar
 778         redef fun tpl_sidebar do return sidebar
 779
 780         redef fun tpl_title do return "{mclass.nitdoc_name}{mclass.tpl_signature.write_to_string}"
 781
 782         redef fun tpl_topmenu do
 783                 var topmenu = super
 784                 var mmodule: MModule
 785                 if mclass.public_owner == null then
 786                         mmodule = mclass.intro_mmodule
 787                 else
 788                         mmodule = mclass.public_owner.as(not null)
 789                 end
 790                 topmenu.add_item(new TplLink("index.html", "Overview"), false)
 791                 topmenu.add_item(new TplLink("{mmodule.nitdoc_url}", "{mmodule.nitdoc_name}"), false)
 792                 topmenu.add_item(new TplLink("#", "{mclass.nitdoc_name}"), true)
 793                 topmenu.add_item(new TplLink("search.html", "Index"), false)
 794                 return topmenu
 795         end
 796
 797         # Property list to display in sidebar
 798         fun tpl_sidebar_properties do
 799                 var kind_map = sort_by_kind(mclass_inherited_mprops)
 800                 var summary = new TplList.with_classes(["list-unstyled"])
 801
 802                 tpl_sidebar_list("Virtual types", kind_map["type"].to_a, summary)
 803                 tpl_sidebar_list("Constructors", kind_map["init"].to_a, summary)
 804                 tpl_sidebar_list("Methods", kind_map["fun"].to_a, summary)
 805                 tpl_sidebar.boxes.add new TplSideBox.with_content("All properties", summary)
 806         end
 807
 808         private fun tpl_sidebar_list(name: String, mprops: Array[MProperty], summary: TplList) do
 809                 if mprops.is_empty then return
 810                 name_sorter.sort(mprops)
 811                 var entry = new TplListItem.with_content(name)
 812                 var list = new TplList.with_classes(["list-unstyled", "list-labeled"])
 813                 for mprop in mprops do
 814                         list.add_li tpl_sidebar_item(mprop)
 815                 end
 816                 entry.append list
 817                 summary.elts.add entry
 818         end
 819
 820         private fun tpl_sidebar_item(mprop: MProperty): Template do
 821                 var classes = mprop.intro.tpl_css_classes.to_a
 822                 if not mprops2mdefs.has_key(mprop) then
 823                         classes.add "inherit"
 824                         var lnk = new Template
 825                         lnk.add new TplLabel.with_classes(classes)
 826                         lnk.add mprop.intro.tpl_link
 827                         return lnk
 828                 end
 829                 var defs = mprops2mdefs[mprop]
 830                 if defs.has(mprop.intro) then
 831                         classes.add "intro"
 832                 else
 833                         classes.add "redef"
 834                 end
 835                 var lnk = new Template
 836                 lnk.add new TplLabel.with_classes(classes)
 837                 lnk.add mprop.intro.tpl_anchor
 838                 return lnk
 839         end
 840
 841         private fun tpl_intro: TplSection do
 842                 var section = new TplSection.with_title(mclass.nitdoc_anchor, tpl_title)
 843                 section.subtitle = mclass.tpl_declaration
 844                 var article = new TplArticle("intro")
 845                 var intro = mclass.intro
 846                 var def = intro.tpl_definition
 847                 var location = intro.location
 848                 def.location = tpl_showsource(location)
 849                 article.content = def
 850                 section.add_child article
 851                 return section
 852         end
 853
 854         private fun tpl_concerns(section: TplSection) do
 855                 var mmodules = collect_mmodules(mprops2mdefs.keys)
 856                 var owner_map = sort_by_public_owner(mmodules)
 857                 var owners = owner_map.keys.to_a
 858
 859                 if not owners.is_empty then
 860                         var article = new TplArticle.with_title("concerns", "Concerns")
 861                         name_sorter.sort owners
 862                         var list = new TplList.with_classes(["list-unstyled", "list-definition"])
 863                         for owner in owners do
 864                                 var li = new Template
 865                                 li.add owner.tpl_anchor
 866                                 if owner.mdoc != null then
 867                                         li.add ": "
 868                                         li.add owner.mdoc.short_comment
 869                                 end
 870                                 var smmodules = owner_map[owner].to_a
 871                                 #if not smmodules.length >= 1 then
 872                                         var slist = new TplList.with_classes(["list-unstyled", "list-definition"])
 873                                         name_sorter.sort smmodules
 874                                         for mmodule in smmodules do
 875                                                 if mmodule == owner then continue
 876                                                 var sli = new Template
 877                                                 sli.add mmodule.tpl_anchor
 878                                                 if mmodule.mdoc != null then
 879                                                         sli.add ": "
 880                                                         sli.add mmodule.mdoc.short_comment
 881                                                 end
 882                                                 slist.add_li(sli)
 883                                         end
 884                                         li.add slist
 885                                         list.add_li li
 886                                 #end
 887                         end
 888                         article.content = list
 889                         section.add_child article
 890                 end
 891         end
 892
 893         private fun tpl_inheritance(parent: TplSection) do
 894                 # parents
 895                 var hparents = new HashSet[MClass]
 896                 for c in mclass.in_hierarchy(ctx.mainmodule).direct_greaters do
 897                         if c.visibility < ctx.min_visibility then continue
 898                         hparents.add c
 899                 end
 900
 901                 # ancestors
 902                 var hancestors = new HashSet[MClass]
 903                 for c in mclass.in_hierarchy(ctx.mainmodule).greaters do
 904                         if c == mclass then continue
 905                         if c.visibility < ctx.min_visibility then continue
 906                         if hparents.has(c) then continue
 907                         hancestors.add c
 908                 end
 909
 910                 # children
 911                 var hchildren = new HashSet[MClass]
 912                 for c in mclass.in_hierarchy(ctx.mainmodule).direct_smallers do
 913                         if c.visibility < ctx.min_visibility then continue
 914                         hchildren.add c
 915                 end
 916
 917                 # descendants
 918                 var hdescendants = new HashSet[MClass]
 919                 for c in mclass.in_hierarchy(ctx.mainmodule).smallers do
 920                         if c == mclass then continue
 921                         if c.visibility < ctx.min_visibility then continue
 922                         if hchildren.has(c) then continue
 923                         hdescendants.add c
 924                 end
 925
 926                 # Display lists
 927                 var section = new TplSection.with_title("inheritance", "Inheritance")
 928
 929                 # Graph
 930                 var mclasses = new HashSet[MClass]
 931                 mclasses.add_all hancestors
 932                 mclasses.add_all hparents
 933                 if hchildren.length < 10 then mclasses.add_all hchildren
 934                 if hdescendants.length < 10 then mclasses.add_all hdescendants
 935                 mclasses.add mclass
 936                 var graph = tpl_dot(mclasses)
 937                 if graph != null then section.add_child graph
 938
 939                 # parents
 940                 if not hparents.is_empty then
 941                         var lst = hparents.to_a
 942                         name_sorter.sort lst
 943                         section.add_child tpl_list("parents", "Parents", lst)
 944                 end
 945
 946                 # ancestors
 947                 if not hancestors.is_empty then
 948                         var lst = hancestors.to_a
 949                         name_sorter.sort lst
 950                         section.add_child tpl_list("ancestors", "Ancestors", lst)
 951                 end
 952
 953                 # children
 954                 if not hchildren.is_empty and hchildren.length < 15 then
 955                         var lst = hchildren.to_a
 956                         name_sorter.sort lst
 957                         section.add_child tpl_list("children", "Children", lst)
 958                 end
 959
 960                 # descendants
 961                 if not hdescendants.is_empty and hchildren.length < 15 then
 962                         var lst = hdescendants.to_a
 963                         name_sorter.sort lst
 964                         section.add_child tpl_list("descendants", "Descendants", lst)
 965                 end
 966
 967                 parent.add_child section
 968         end
 969
 970         private fun tpl_list(id: String, title: String, elts: Array[MClass]): TplArticle do
 971                 var article = new TplArticle.with_title(id, title)
 972                 var list = new TplList.with_classes(["list-unstyled", "list-definition"])
 973                 for elt in elts do list.elts.add elt.tpl_list_item
 974                 article.content = list
 975                 return article
 976         end
 977
 978         private fun tpl_properties(parent: TplSection) do
 979                 var mod_map = sort_by_mmodule(mprops2mdefs.keys)
 980                 var owner_map = sort_by_public_owner(mod_map.keys)
 981                 var owners = owner_map.keys.to_a
 982
 983                 for owner in owners do
 984                         var section = new TplSection(owner.nitdoc_anchor)
 985                         var title = new Template
 986                         title.add "Introductions in "
 987                         title.add owner.tpl_link
 988                         section.title = title
 989                         section.summary_title = "In {owner.nitdoc_name}"
 990                         for mmodule in owner_map[owner] do
 991                                 # properties
 992                                 var mprops = mod_map[mmodule]
 993                                 var kind_map = sort_by_kind(mprops)
 994
 995                                 # virtual types
 996                                 var elts = kind_map["type"].to_a
 997                                 name_sorter.sort(elts)
 998                                 for elt in elts do
 999                                         var defs = mprops2mdefs[elt].to_a
1000                                         section.add_child tpl_mprop_article(elt, defs)
1001                                 end
1002
1003                                 # constructors
1004                                 elts = kind_map["init"].to_a
1005                                 name_sorter.sort(elts)
1006                                 for elt in elts do
1007                                         var defs = mprops2mdefs[elt].to_a
1008                                         section.add_child tpl_mprop_article(elt, defs)
1009                                 end
1010
1011                                 # methods
1012                                 elts = kind_map["fun"].to_a
1013                                 name_sorter.sort(elts)
1014                                 for elt in elts do
1015                                         var defs = mprops2mdefs[elt].to_a
1016                                         section.add_child tpl_mprop_article(elt, defs)
1017                                 end
1018                         end
1019                         parent.add_child section
1020                 end
1021         end
1022
1023         redef fun tpl_content do
1024                 tpl_sidebar_properties
1025                 var top = tpl_intro
1026                 tpl_concerns(top)
1027                 tpl_inheritance(top)
1028                 tpl_properties(top)
1029                 tpl_page.add_section top
1030         end
1031
1032         private fun sort_by_mproperty(mpropdefs: Collection[MPropDef]): Map[MProperty, Set[MPropDef]] do
1033                 var map = new HashMap[MProperty, Set[MPropDef]]
1034                 for mpropdef in mpropdefs do
1035                         var mproperty = mpropdef.mproperty
1036                         if not map.has_key(mproperty) then map[mproperty] = new HashSet[MPropDef]
1037                         map[mproperty].add mpropdef
1038                 end
1039                 return map
1040         end
1041
1042         private fun sort_by_mmodule(mprops: Collection[MProperty]): Map[MModule, Set[MProperty]] do
1043                 var map = new HashMap[MModule, Set[MProperty]]
1044                 for mprop in mprops do
1045                         var mpropdefs = mprops2mdefs[mprop].to_a
1046                         ctx.mainmodule.linearize_mpropdefs(mpropdefs)
1047                         var mmodule = mpropdefs.first.mclassdef.mmodule
1048                         if not map.has_key(mmodule) then map[mmodule] = new HashSet[MProperty]
1049                         map[mmodule].add mprop
1050                 end
1051                 return map
1052         end
1053
1054         private fun sort_by_kind(mprops: Collection[MProperty]): Map[String, Set[MProperty]] do
1055                 var map = new HashMap[String, Set[MProperty]]
1056                 map["type"] = new HashSet[MProperty]
1057                 map["init"] = new HashSet[MProperty]
1058                 map["fun"] = new HashSet[MProperty]
1059                 for mprop in mprops do
1060                         if mprop isa MVirtualTypeProp then
1061                                 map["type"].add mprop
1062                         else if mprop isa MMethod then
1063                                 if mprop.is_init then
1064                                         map["init"].add mprop
1065                                 else
1066                                         map["fun"].add mprop
1067                                 end
1068                         end
1069                 end
1070                 return map
1071         end
1072
1073         private fun mclass_inherited_mprops: Set[MProperty] do
1074                 var res = new HashSet[MProperty]
1075                 var local = mclass.local_mproperties(ctx.min_visibility)
1076                 for mprop in mclass.inherited_mproperties(ctx.mainmodule, ctx.min_visibility) do
1077                         if local.has(mprop) then continue
1078                         #if mprop isa MMethod and mprop.is_init then continue
1079                         if mprop.intro.mclassdef.mclass.name == "Object" and
1080                                 (mprop.visibility == protected_visibility or
1081                                 mprop.intro.mclassdef.mmodule.name != "kernel") then continue
1082                         res.add mprop
1083                 end
1084                 res.add_all local
1085                 return res
1086         end
1087
1088         private fun collect_mmodules(mprops: Collection[MProperty]): Set[MModule] do
1089                 var res = new HashSet[MModule]
1090                 for mprop in mprops do
1091                         if mprops2mdefs.has_key(mprop) then
1092                                 for mpropdef in mprops2mdefs[mprop] do res.add mpropdef.mclassdef.mmodule
1093                         end
1094                 end
1095                 return res
1096         end
1097
1098         private fun sort_by_public_owner(mmodules: Collection[MModule]): Map[MModule, Set[MModule]] do
1099                 var map = new HashMap[MModule, Set[MModule]]
1100                 for mmodule in mmodules do
1101                         var owner = mmodule
1102                         if mmodule.public_owner != null then owner = mmodule.public_owner.as(not null)
1103                         if not map.has_key(owner) then map[owner] = new HashSet[MModule]
1104                         map[owner].add mmodule
1105                 end
1106                 return map
1107         end
1108
1109         # Generate dot hierarchy for classes
1110         fun tpl_dot(mclasses: Collection[MClass]): nullable TplArticle do
1111                 var poset = new POSet[MClass]
1112
1113                 for mclass in mclasses do
1114                         poset.add_node mclass
1115                         for oclass in mclasses do
1116                                 poset.add_node oclass
1117                                 if mclass.in_hierarchy(ctx.mainmodule) < oclass then
1118                                         poset.add_edge(mclass, oclass)
1119                                 end
1120                         end
1121                 end
1122
1123                 var op = new FlatBuffer
1124                 var name = "dep_{mclass.name}"
1125                 op.append("digraph {name} \{ rankdir=BT; node[shape=none,margin=0,width=0,height=0,fontsize=10]; edge[dir=none,color=gray]; ranksep=0.2; nodesep=0.1;\n")
1126                 for c in poset do
1127                         if c == mclass then
1128                                 op.append("\"{c.name}\"[shape=box,margin=0.03];\n")
1129                         else
1130                                 op.append("\"{c.name}\"[URL=\"{c.nitdoc_url}\"];\n")
1131                         end
1132                         for c2 in poset[c].direct_greaters do
1133                                 op.append("\"{c.name}\"->\"{c2.name}\";\n")
1134                         end
1135                 end
1136                 op.append("\}\n")
1137                 return tpl_graph(op, name, "Inheritance graph")
1138         end
1139 end
1140