From: Jean Privat Date: Fri, 24 Apr 2015 06:03:24 +0000 (+0700) Subject: Merge: nitdoc: prepare the migration of nitdoc component to new phases X-Git-Tag: v0.7.4~4 X-Git-Url: http://nitlanguage.org?hp=a0a920e1d115d8051744dbcd85a3b55807612e6c Merge: nitdoc: prepare the migration of nitdoc component to new phases Only internal modification, no diff with the generated HTML of the previous version. If you don't trust me (I you shouldn't), the demos will be [there](http://gresil.org/jenkins/job/CI-nitdoc/ws/doc/stdlib/index.html) and [there](http://gresil.org/jenkins/job/CI-nitdoc/ws/doc/nitc/index.html) in a few minutes. > Brace yourself, next PR on that subject will be big. Pull-Request: #1293 Reviewed-by: Jean Privat --- diff --git a/src/doc/doc_phases/doc_html.nit b/src/doc/doc_phases/doc_html.nit index ef74992..3329fc5 100644 --- a/src/doc/doc_phases/doc_html.nit +++ b/src/doc/doc_phases/doc_html.nit @@ -246,9 +246,9 @@ redef class OverviewPage var sarticle = mproject.tpl_article sarticle.subtitle = mproject.html_declaration sarticle.content = mproject.tpl_definition - var mdoc = mproject.mdoc_or_fallback - if mdoc != null then - sarticle.content = mdoc.tpl_short_comment + var comment = mproject.html_short_comment + if comment != null then + sarticle.content = comment end ssection.add_child sarticle end @@ -659,9 +659,6 @@ redef class DefinitionArticle if mentity isa MPropDef then article.source_link = v.tpl_showsource(mentity.location) end - if not mentity isa MVirtualTypeProp then - # article.content = mentity.tpl_comment - end end for child in children do child.render(v, doc, page, article) @@ -714,8 +711,9 @@ redef class DefinitionArticle article.title_classes.add "signature" article.summary_title = "{mprop.html_name}" article.subtitle = mpropdef.html_namespace - if mpropdef.mdoc_or_fallback != null then - article.content = mpropdef.mdoc_or_fallback.tpl_comment + var comment = mpropdef.html_comment + if comment != null then + article.content = comment end # TODO move in its own phase? let's see after doc_template refactoring. # Add linearization @@ -842,3 +840,317 @@ redef class GraphArticle parent.add_child article end end + +redef class Location + # Github url based on this location + fun github(gitdir: String): String do + var base_dir = getcwd.join_path(gitdir).simplify_path + var file_loc = getcwd.join_path(file.filename).simplify_path + var gith_loc = file_loc.substring(base_dir.length + 1, file_loc.length) + return "{gith_loc}:{line_start},{column_start}--{line_end},{column_end}" + end +end + +redef class MEntity + # A template article that briefly describe the entity + fun tpl_short_article: TplArticle do + var tpl = tpl_article + var comment = html_short_comment + if comment != null then + tpl.content = comment + end + return tpl + end + + # A template article that describe the entity + fun tpl_article: TplArticle do + var tpl = new TplArticle.with_title(nitdoc_id, tpl_title) + tpl.title_classes.add "signature" + tpl.subtitle = html_namespace + tpl.summary_title = html_name + return tpl + end + + # A template definition of the mentity + # include name, sysnopsys, comment and namespace + fun tpl_definition: TplDefinition is abstract + + # A li element that can go in a list + fun tpl_list_item: TplListItem do + var lnk = new Template + lnk.add new TplLabel.with_classes(tpl_css_classes) + lnk.add html_link + var comment = html_short_comment + if comment != null then + lnk.add ": " + lnk.add comment + end + return new TplListItem.with_content(lnk) + end + + var tpl_css_classes = new Array[String] + + # Box title for this mentity + fun tpl_title: Template do + var title = new Template + title.add tpl_icon + title.add html_namespace + return title + end + + # Icon that will be displayed before the title + fun tpl_icon: TplIcon do + var icon = new TplIcon.with_icon("tag") + icon.css_classes.add_all(tpl_css_classes) + return icon + end +end + +redef class MConcern + # Return a li element for `self` that can be displayed in a concern list + private fun tpl_concern_item: TplListItem do + var lnk = new Template + lnk.add html_link_to_anchor + var comment = html_short_comment + if comment != null then + lnk.add ": " + lnk.add comment + end + return new TplListItem.with_content(lnk) + end +end + +redef class MProject + redef fun tpl_definition do + var tpl = new TplDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end + + redef fun tpl_css_classes do return ["public"] +end + +redef class MGroup + redef fun tpl_definition do + var tpl = new TplDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end +end + +redef class MModule + redef fun tpl_definition do + var tpl = new TplClassDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end + + redef fun tpl_css_classes do return ["public"] +end + +redef class MClass + redef fun tpl_definition do return intro.tpl_definition + + redef fun tpl_title do + var title = new Template + title.add tpl_icon + title.add html_link + return title + end + + redef fun tpl_icon do return intro.tpl_icon + redef fun tpl_css_classes do return intro.tpl_css_classes +end + +redef class MClassDef + redef fun tpl_article do + var tpl = new TplArticle(nitdoc_id) + tpl.summary_title = "in {mmodule.html_name}" + tpl.title = html_declaration + tpl.title_classes.add "signature" + var title = new Template + title.add "in " + title.add mmodule.html_namespace + tpl.subtitle = title + var comment = html_comment + if comment != null then + tpl.content = comment + end + return tpl + end + + redef fun tpl_title do + var title = new Template + title.add tpl_icon + title.add html_link + return title + end + + redef fun tpl_definition do + var tpl = new TplClassDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end + + redef fun tpl_css_classes do + var set = new HashSet[String] + if is_intro then set.add "intro" + for m in mclass.intro.modifiers do set.add m.to_cmangle + for m in modifiers do set.add m.to_cmangle + return set.to_a + end + + fun tpl_modifiers: Template do + var tpl = new Template + for modifier in modifiers do + if modifier == "public" then continue + tpl.add "{modifier.html_escape} " + end + return tpl + end +end + +redef class MProperty + redef fun tpl_title do return intro.tpl_title + redef fun tpl_icon do return intro.tpl_icon + redef fun tpl_css_classes do return intro.tpl_css_classes +end + +redef class MPropDef + redef fun tpl_article do + var tpl = new TplArticle(nitdoc_id) + tpl.summary_title = "in {mclassdef.html_name}" + var title = new Template + title.add "in " + title.add mclassdef.html_link + tpl.title = title + tpl.subtitle = html_declaration + var comment = html_comment + if comment != null then + tpl.content = comment + end + return tpl + end + + redef fun tpl_definition do + var tpl = new TplDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end + + redef fun tpl_css_classes do + var set = new HashSet[String] + if is_intro then set.add "intro" + for m in mproperty.intro.modifiers do set.add m.to_cmangle + for m in modifiers do set.add m.to_cmangle + return set.to_a + end + + fun tpl_modifiers: Template do + var tpl = new Template + for modifier in modifiers do + if modifier == "public" then continue + tpl.add "{modifier.html_escape} " + end + return tpl + end + + redef fun tpl_list_item do + var lnk = new Template + lnk.add new TplLabel.with_classes(tpl_css_classes.to_a) + var atext = html_link.text + var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" + var atitle = html_link.title + var anchor = new Link.with_title(ahref, atext, atitle) + lnk.add anchor + var comment = html_short_comment + if comment != null then + lnk.add ": " + lnk.add comment + end + return new TplListItem.with_content(lnk) + end + + fun tpl_inheritance_item: TplListItem do + var lnk = new Template + lnk.add new TplLabel.with_classes(tpl_css_classes.to_a) + lnk.add mclassdef.mmodule.html_namespace + lnk.add "::" + var atext = mclassdef.html_link.text + var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" + var atitle = mclassdef.html_link.title + var anchor = new Link.with_title(ahref, atext, atitle) + lnk.add anchor + var comment = html_short_comment + if comment != null then + lnk.add ": " + lnk.add comment + end + var li = new TplListItem.with_content(lnk) + li.css_classes.add "signature" + return li + end +end + +redef class ConcernsTree + + private var seen = new HashSet[MConcern] + + redef fun add(p, e) do + if seen.has(e) then return + seen.add e + super(p, e) + end + + fun to_tpl: TplList do + var lst = new TplList.with_classes(["list-unstyled", "list-definition"]) + for r in roots do + var li = r.tpl_concern_item + lst.add_li li + build_list(r, li) + end + return lst + end + + private fun build_list(e: MConcern, li: TplListItem) do + if not sub.has_key(e) then return + var subs = sub[e] + var lst = new TplList.with_classes(["list-unstyled", "list-definition"]) + for e2 in subs do + if e2 isa MGroup and e2.is_root then + build_list(e2, li) + else + var sli = e2.tpl_concern_item + lst.add_li sli + build_list(e2, sli) + end + end + li.append lst + end +end + +redef class MInnerClassDef + redef fun tpl_definition do + var tpl = new TplClassDefinition + var comment = html_comment + if comment != null then + tpl.comment = comment + end + return tpl + end +end diff --git a/src/doc/html_templates/html_model.nit b/src/doc/html_templates/html_model.nit index a37dd2b..f3c2751 100644 --- a/src/doc/html_templates/html_model.nit +++ b/src/doc/html_templates/html_model.nit @@ -21,16 +21,6 @@ import html_components import html::bootstrap import ordered_tree -redef class Location - # Github url based on this location - fun github(gitdir: String): String do - var base_dir = getcwd.join_path(gitdir).simplify_path - var file_loc = getcwd.join_path(file.filename).simplify_path - var gith_loc = file_loc.substring(base_dir.length + 1, file_loc.length) - return "{gith_loc}:{line_start},{column_start}--{line_end},{column_end}" - end -end - redef class MEntity # ID used as a HTML unique ID and in file names. # @@ -114,71 +104,18 @@ redef class MEntity # * MPropdef: `mclassdef:mpropdef` fun html_namespace: Template is abstract - # A template article that briefly describe the entity - fun tpl_short_article: TplArticle do - var tpl = tpl_article + # Returns the comment of this MEntity formatted as HTML. + var html_comment: nullable Writable is lazy do var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.content = mdoc.tpl_short_comment - end - return tpl - end - - # A template article that describe the entity - fun tpl_article: TplArticle do - var tpl = new TplArticle.with_title(nitdoc_id, tpl_title) - tpl.title_classes.add "signature" - tpl.subtitle = html_namespace - tpl.summary_title = html_name - return tpl - end - - # A template definition of the mentity - # include name, sysnopsys, comment and namespace - fun tpl_definition: TplDefinition is abstract - - # A li element that can go in a list - fun tpl_list_item: TplListItem do - var lnk = new Template - lnk.add new TplLabel.with_classes(tpl_css_classes) - lnk.add html_link - var mdoc = mdoc_or_fallback - if mdoc != null then - lnk.add ": " - lnk.add mdoc.tpl_short_comment - end - return new TplListItem.with_content(lnk) + if mdoc == null then return null + return mdoc.tpl_comment end - var tpl_css_classes = new Array[String] - - # Box title for this mentity - fun tpl_title: Template do - var title = new Template - title.add tpl_icon - title.add html_namespace - return title - end - - # Icon that will be displayed before the title - fun tpl_icon: TplIcon do - var icon = new TplIcon.with_icon("tag") - icon.css_classes.add_all(tpl_css_classes) - return icon - end -end - -redef class MConcern - # Return a li element for `self` that can be displayed in a concern list - private fun tpl_concern_item: TplListItem do - var lnk = new Template - lnk.add html_link_to_anchor + # Returns the comment of this MEntity formatted as HTML. + var html_short_comment: nullable Writable is lazy do var mdoc = mdoc_or_fallback - if mdoc != null then - lnk.add ": " - lnk.add mdoc.tpl_short_comment - end - return new TplListItem.with_content(lnk) + if mdoc == null then return null + return mdoc.tpl_short_comment end end @@ -187,17 +124,6 @@ redef class MProject redef fun nitdoc_url do return root.nitdoc_url redef var html_modifiers = ["project"] redef fun html_namespace do return html_link - - redef fun tpl_definition do - var tpl = new TplDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_css_classes do return ["public"] end redef class MGroup @@ -224,15 +150,6 @@ redef class MGroup end return tpl end - - redef fun tpl_definition do - var tpl = new TplDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end end redef class MModule @@ -263,17 +180,6 @@ redef class MModule tpl.add html_link return tpl end - - redef fun tpl_definition do - var tpl = new TplClassDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_css_classes do return ["public"] end redef class MClass @@ -315,18 +221,6 @@ redef class MClass # Returns `intro.html_signature`. fun html_signature: Template do return intro.html_signature - - redef fun tpl_definition do return intro.tpl_definition - - redef fun tpl_title do - var title = new Template - title.add tpl_icon - title.add html_link - return title - end - - redef fun tpl_icon do return intro.tpl_icon - redef fun tpl_css_classes do return intro.tpl_css_classes end redef class MClassDef @@ -407,55 +301,6 @@ redef class MClassDef end return tpl end - - redef fun tpl_article do - var tpl = new TplArticle(nitdoc_id) - tpl.summary_title = "in {mmodule.html_name}" - tpl.title = html_declaration - tpl.title_classes.add "signature" - var title = new Template - title.add "in " - title.add mmodule.html_namespace - tpl.subtitle = title - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.content = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_title do - var title = new Template - title.add tpl_icon - title.add html_link - return title - end - - redef fun tpl_definition do - var tpl = new TplClassDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_css_classes do - var set = new HashSet[String] - if is_intro then set.add "intro" - for m in mclass.intro.modifiers do set.add m.to_cmangle - for m in modifiers do set.add m.to_cmangle - return set.to_a - end - - fun tpl_modifiers: Template do - var tpl = new Template - for modifier in modifiers do - if modifier == "public" then continue - tpl.add "{modifier.html_escape} " - end - return tpl - end end redef class MProperty @@ -480,12 +325,6 @@ redef class MProperty # Returns `intro.html_signature`. fun html_signature: Template do return intro.html_signature - - redef fun tpl_title do return intro.tpl_title - - redef fun tpl_icon do return intro.tpl_icon - - redef fun tpl_css_classes do return intro.tpl_css_classes end redef class MPropDef @@ -539,83 +378,6 @@ redef class MPropDef # Returns the MPropDef signature with static types. fun html_signature: Template is abstract - - redef fun tpl_article do - var tpl = new TplArticle(nitdoc_id) - tpl.summary_title = "in {mclassdef.html_name}" - var title = new Template - title.add "in " - title.add mclassdef.html_link - tpl.title = title - tpl.subtitle = html_declaration - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.content = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_definition do - var tpl = new TplDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end - - redef fun tpl_css_classes do - var set = new HashSet[String] - if is_intro then set.add "intro" - for m in mproperty.intro.modifiers do set.add m.to_cmangle - for m in modifiers do set.add m.to_cmangle - return set.to_a - end - - fun tpl_modifiers: Template do - var tpl = new Template - for modifier in modifiers do - if modifier == "public" then continue - tpl.add "{modifier.html_escape} " - end - return tpl - end - - redef fun tpl_list_item do - var lnk = new Template - lnk.add new TplLabel.with_classes(tpl_css_classes.to_a) - var atext = html_link.text - var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" - var atitle = html_link.title - var anchor = new Link.with_title(ahref, atext, atitle) - lnk.add anchor - var mdoc = mdoc_or_fallback - if mdoc != null then - lnk.add ": " - lnk.add mdoc.tpl_short_comment - end - return new TplListItem.with_content(lnk) - end - - fun tpl_inheritance_item: TplListItem do - var lnk = new Template - lnk.add new TplLabel.with_classes(tpl_css_classes.to_a) - lnk.add mclassdef.mmodule.html_namespace - lnk.add "::" - var atext = mclassdef.html_link.text - var ahref = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" - var atitle = mclassdef.html_link.title - var anchor = new Link.with_title(ahref, atext, atitle) - lnk.add anchor - var mdoc = mdoc_or_fallback - if mdoc != null then - lnk.add ": " - lnk.add mdoc.tpl_short_comment - end - var li = new TplListItem.with_content(lnk) - li.css_classes.add "signature" - return li - end end redef class MAttributeDef @@ -809,44 +571,6 @@ redef class MParameter end end -redef class ConcernsTree - - private var seen = new HashSet[MConcern] - - redef fun add(p, e) do - if seen.has(e) then return - seen.add e - super(p, e) - end - - fun to_tpl: TplList do - var lst = new TplList.with_classes(["list-unstyled", "list-definition"]) - for r in roots do - var li = r.tpl_concern_item - lst.add_li li - build_list(r, li) - end - return lst - end - - private fun build_list(e: MConcern, li: TplListItem) do - if not sub.has_key(e) then return - var subs = sub[e] - var lst = new TplList.with_classes(["list-unstyled", "list-definition"]) - for e2 in subs do - if e2 isa MGroup and e2.is_root then - build_list(e2, li) - else - var sli = e2.tpl_concern_item - lst.add_li sli - build_list(e2, sli) - end - end - li.append lst - end -end - - ################################################################################ # Additions to `model_ext`. @@ -876,13 +600,4 @@ redef class MInnerClassDef redef fun html_link_to_anchor do return inner.html_link_to_anchor redef fun html_link do return inner.html_link redef fun html_signature do return inner.html_signature - - redef fun tpl_definition do - var tpl = new TplClassDefinition - var mdoc = mdoc_or_fallback - if mdoc != null then - tpl.comment = mdoc.tpl_comment - end - return tpl - end end diff --git a/src/doc/html_templates/html_templates.nit b/src/doc/html_templates/html_templates.nit index 53fc0cf..540ec24 100644 --- a/src/doc/html_templates/html_templates.nit +++ b/src/doc/html_templates/html_templates.nit @@ -196,3 +196,72 @@ class DocTopMenu addn "" end end + +redef class DocComposite + super Template + + # HTML anchor id + var html_id: String is noinit + + # Title to display if any. + # + # This title can be decorated with HTML. + var html_title: nullable Writable is noinit, writable + + # Subtitle to display if any. + var html_subtitle: nullable Writable is noinit, writable + + # Render the element title and subtitle. + private fun render_title do + if html_title != null then + addn new Header(hlvl, html_title.write_to_string) + end + if html_subtitle != null then + addn "
" + addn html_subtitle.write_to_string + addn "
" + end + end + + # Render the element body. + private fun render_body do end + + redef fun rendering do + if is_hidden then return + render_title + render_body + end + + # Level for HTML heading. + private fun hlvl: Int do + if parent == null then return 1 + return parent.hlvl + 1 + end + + # Is `self` not displayed in the page. + # + # By default, empty elements are hidden. + fun is_hidden: Bool do return is_empty +end + +redef class DocSection + super BSComponent + + redef fun rendering do + if is_hidden then + addn "" + return + end + render_body + end +end + +redef class DocArticle + super BSComponent + + # Never displays the title for article. + # + # This is to maintain compatibility with old components, this may change + # without notice in further version. + redef fun render_title do end +end