src/doc/doc_down.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 # Handle markdown formatting in Nit comments.
  16 module doc_down
  17
  18 import markdown
  19 import htmlight
  20 private import parser_util
  21
  22 redef class MDoc
  23
  24         private var markdown_proc: MarkdownProcessor is lazy, writable do
  25                 return original_mentity.as(not null).model.nitdoc_md_processor
  26         end
  27
  28         private var inline_proc: MarkdownProcessor is lazy, writable do
  29                 return original_mentity.as(not null).model.nitdoc_inline_processor
  30         end
  31
  32         # Renders the synopsis as a HTML comment block.
  33         var html_synopsis: Writable is lazy do
  34                 var res = new Template
  35                 var syn = inline_proc.process(content.first)
  36                 res.add "<span class=\"synopsys nitdoc\">{syn}</span>"
  37                 return res
  38         end
  39
  40         # Renders the synopsis as a HTML comment block.
  41         var md_synopsis: Writable is lazy do
  42                 if content.is_empty then return ""
  43                 return content.first
  44         end
  45
  46         # Renders the comment without the synopsis as a HTML comment block.
  47         var html_comment: Writable is lazy do
  48                 var lines = content.to_a
  49                 if not lines.is_empty then lines.shift
  50                 return lines_to_html(lines)
  51         end
  52
  53         #
  54         var md_comment: Writable is lazy do
  55                 if content.is_empty then return ""
  56                 var lines = content.to_a
  57                 lines.shift
  58                 return lines.join("\n")
  59         end
  60
  61         # Renders the synopsis and the comment as a HTML comment block.
  62         var html_documentation: Writable is lazy do return lines_to_html(content.to_a)
  63
  64         # Renders the synopsis and the comment as a HTML comment block.
  65         var md_documentation: Writable is lazy do return lines_to_md(content.to_a)
  66
  67         # Renders markdown line as a HTML comment block.
  68         private fun lines_to_html(lines: Array[String]): Writable do
  69                 var res = new Template
  70                 var decorator = markdown_proc.decorator.as(NitdocDecorator)
  71                 decorator.current_mdoc = self
  72                 res.add "<div class=\"nitdoc\">"
  73                 # do not use DocUnit as synopsys
  74                 if not lines.is_empty then
  75                         if not lines.first.has_prefix("    ") and
  76                            not lines.first.has_prefix("\t") then
  77                                 # parse synopsys
  78                                 var syn = inline_proc.process(lines.shift)
  79                                 res.add "<h1 class=\"synopsys\">{syn}</h1>"
  80                         end
  81                 end
  82                 # check for annotations
  83                 for i in [0 .. lines.length[ do
  84                         var line = lines[i]
  85                         if line.to_upper.has_prefix("ENSURE") or line.to_upper.has_prefix("REQUIRE") then
  86                                 var html = inline_proc.process(line)
  87                                 lines[i] = "<p class=\"contract\">{html}</p>"
  88                         else if line.to_upper.has_prefix("TODO") or line.to_upper.has_prefix("FIXME") then
  89                                 var html = inline_proc.process(line)
  90                                 lines[i] = "<p class=\"todo\">{html}</p>"
  91                         end
  92                 end
  93                 # add other lines
  94                 res.add markdown_proc.process(lines.join("\n"))
  95                 res.add "</div>"
  96                 decorator.current_mdoc = null
  97                 return res
  98         end
  99
 100         private fun lines_to_md(lines: Array[String]): Writable do
 101                 var res = new Template
 102                 if not lines.is_empty then
 103                         var syn = lines.first
 104                         if not syn.has_prefix("    ") and not syn.has_prefix("\t") and
 105                           not syn.trim.has_prefix("#") then
 106                                 lines.shift
 107                                 res.add "# {syn}\n"
 108                         end
 109                 end
 110                 res.add lines.join("\n")
 111                 return res
 112         end
 113 end
 114
 115 # The specific markdown decorator used internally to process MDoc object.
 116 #
 117 # You should use the various methods of `MDoc` like `MDoc::html_documentation`
 118 #
 119 # The class is public so specific behavior can be plugged on it.
 120 class NitdocDecorator
 121         super HTMLDecorator
 122
 123         private var toolcontext = new ToolContext
 124
 125         # The currently processed mdoc.
 126         #
 127         # Unfortunately, this seems to be the simpler way to get the currently processed `MDoc` object.
 128         var current_mdoc: nullable MDoc = null
 129
 130         redef fun add_code(v, block) do
 131                 var meta = block.meta or else "nit"
 132
 133                 # Do not try to highlight non-nit code.
 134                 if meta != "nit" and meta != "nitish" then
 135                         v.add "<pre class=\"{meta}\"><code>"
 136                         v.emit_in block
 137                         v.add "</code></pre>\n"
 138                         return
 139                 end
 140                 # Try to parse code
 141                 var code = block.raw_content
 142                 var ast = toolcontext.parse_something(code)
 143                 if ast isa AError then
 144                         v.add "<pre class=\"{meta}\"><code>"
 145                         v.emit_in block
 146                         v.add "</code></pre>\n"
 147                         return
 148                 end
 149                 v.add "<pre class=\"nitcode\"><code>"
 150                 var hl = new HtmlightVisitor
 151                 hl.line_id_prefix = ""
 152                 hl.highlight_node(ast)
 153                 v.add(hl.html)
 154                 v.add "</code></pre>\n"
 155         end
 156
 157         redef fun add_span_code(v, text, from, to) do
 158                 # Try to parse it
 159                 var code = code_from_text(text, from, to)
 160                 var ast = toolcontext.parse_something(code)
 161
 162                 if ast isa AError then
 163                         v.add "<code class=\"rawcode\">"
 164                         append_code(v, text, from, to)
 165                 else
 166                         v.add "<code class=\"nitcode\">"
 167                         var hl = new HtmlightVisitor
 168                         hl.line_id_prefix = ""
 169                         hl.highlight_node(ast)
 170                         v.add(hl.html)
 171                 end
 172                 v.add "</code>"
 173         end
 174
 175         private fun code_from_text(buffer: Text, from, to: Int): String do
 176                 var out = new FlatBuffer
 177                 for i in [from..to[ do out.add buffer[i]
 178                 return out.write_to_string
 179         end
 180 end
 181
 182 # Decorator for span elements.
 183 #
 184 # Because inline comments can appear as span elements,
 185 # InlineDecorator do not decorate things like paragraphs or headers.
 186 private class InlineDecorator
 187         super NitdocDecorator
 188
 189         redef fun add_paragraph(v, block) do
 190                 v.emit_in block
 191         end
 192
 193         redef fun add_headline(v, block) do
 194                 # save headline
 195                 var line = block.block.first_line
 196                 if line == null then return
 197                 var txt = line.value
 198                 var id = strip_id(txt)
 199                 var lvl = block.depth
 200                 headlines[id] = new HeadLine(id, txt, lvl)
 201
 202                 v.emit_in block
 203         end
 204
 205         redef fun add_code(v, block) do
 206                 # Try to parse code
 207                 var ast = toolcontext.parse_something(block.block.text.to_s)
 208                 if ast isa AError then
 209                         v.add "<code>"
 210                         v.emit_in block
 211                         v.add "</code>"
 212                         return
 213                 end
 214                 v.add "<code class=\"nitcode\">"
 215                 var hl = new HtmlightVisitor
 216                 hl.highlight_node(ast)
 217                 v.add(hl.html)
 218                 v.add "</code>"
 219         end
 220 end
 221
 222 redef class Model
 223         # Get a markdown processor for Nitdoc comments.
 224         var nitdoc_md_processor: MarkdownProcessor is lazy, writable do
 225                 var proc = new MarkdownProcessor
 226                 proc.decorator = new NitdocDecorator
 227                 return proc
 228         end
 229
 230         # Get a markdown inline processor for Nitdoc comments.
 231         #
 232         # This processor is specificaly designed to inlinable doc elements like synopsys.
 233         var nitdoc_inline_processor: MarkdownProcessor is lazy, writable do
 234                 var proc = new MarkdownProcessor
 235                 proc.decorator = new InlineDecorator
 236                 return proc
 237         end
 238 end