first implementation of docgen2

compiler/docgen.nim

@@ -18,13 +18,13 @@ import
 
 type
   TSections = array[TSymKind, PRope]
-  TDocumentor = object of rstgen.TRstGenerator
+  TDocumentor* = object of rstgen.TRstGenerator
     modDesc: PRope           # module description
     id: int                  # for generating IDs
     toc, section: TSections
     indexValFilename: string
 
-  PDoc = ref TDocumentor
+  PDoc* = ref TDocumentor
   
 proc compilerMsgHandler(filename: string, line, col: int,
                         msgKind: rst.TMsgKind, arg: string) {.procvar.} =
@@ -48,7 +48,7 @@ proc parseRst(text, filename: string,
   result = rstParse(text, filename, line, column, hasToc, rstOptions,
                     options.FindFile, compilerMsgHandler)
 
-proc newDocumentor(filename: string, config: PStringTable): PDoc = 
+proc newDocumentor*(filename: string, config: PStringTable): PDoc = 
   new(result)
   initRstGenerator(result[], (if gCmd != cmdRst2Tex: outHtml else: outLatex),
                    options.gConfigVars, filename, {roSupportRawDirective},
@@ -114,9 +114,9 @@ proc ropeFormatNamedVars(frmt: TFormatStr, varnames: openarray[string],
         else: rawMessage(errUnkownSubstitionVar, id)
       else: InternalError("ropeFormatNamedVars")
     var start = i
-    while i < L: 
-      if (frmt[i] != '$'): inc(i)
-      else: break 
+    while i < L:
+      if frmt[i] != '$': inc(i)
+      else: break
     if i - 1 >= start: app(result, substr(frmt, start, i - 1))
 
 proc genComment(d: PDoc, n: PNode): string =
@@ -243,7 +243,7 @@ proc traceDeps(d: PDoc, n: PNode) =
         "<a class=\"reference external\" href=\"$1.html\">$1</a>", 
         "$1", [toRope(getModuleName(n))])
 
-proc generateDoc(d: PDoc, n: PNode) = 
+proc generateDoc*(d: PDoc, n: PNode) = 
   case n.kind
   of nkCommentStmt: app(d.modDesc, genComment(d, n))
   of nkProcDef: genItem(d, n, n.sons[namePos], skProc)
@@ -317,12 +317,12 @@ proc genOutFile(d: PDoc): PRope =
     code = content
   result = code
 
-proc generateIndex(d: PDoc) =
+proc generateIndex*(d: PDoc) =
   if optGenIndex in gGlobalOptions:
     writeIndexFile(d[], splitFile(options.outFile).dir / 
                         splitFile(d.filename).name & indexExt)
 
-proc writeOutput(d: PDoc, filename, outExt: string) = 
+proc writeOutput*(d: PDoc, filename, outExt: string) = 
   var content = genOutFile(d)
   if optStdout in gGlobalOptions:
     writeRope(stdout, content)

compiler/docgen2.nim

@@ -0,0 +1,50 @@
+#
+#
+#           The Nimrod Compiler
+#        (c) Copyright 2012 Andreas Rumpf
+#
+#    See the file "copying.txt", included in this
+#    distribution, for details about the copyright.
+#
+
+# This module implements a new documentation generator that runs after
+# semantic checking.
+
+import 
+  os, options, ast, astalgo, msgs, ropes, idents, passes, docgen
+
+type 
+  TGen = object of TPassContext
+    doc: PDoc
+    module: PSym
+    filename: string
+  PGen = ref TGen
+
+proc close(p: PPassContext, n: PNode): PNode =
+  var g = PGen(p)
+  writeOutput(g.doc, g.filename, HtmlExt)
+  generateIndex(g.doc)
+
+proc processNode(c: PPassContext, n: PNode): PNode = 
+  result = n
+  var g = PGen(c)
+  generateDoc(g.doc, n)
+
+proc myOpen(module: PSym, filename: string): PPassContext = 
+  var g: PGen
+  new(g)
+  g.module = module
+  g.filename = filename
+  var d = newDocumentor(filename, options.gConfigVars)
+  d.hasToc = true
+  g.doc = d
+  result = g
+
+proc docgen2Pass*(): TPass = 
+  initPass(result)
+  result.open = myOpen
+  result.process = processNode
+  result.close = close
+
+proc finishDoc2Pass*(project: string) = 
+  nil

compiler/main.nim

@@ -16,7 +16,7 @@ import
   wordrecg, sem, semdata, idents, passes, docgen, extccomp,
   cgen, ecmasgen,
   platform, nimconf, importer, passaux, depends, transf, evals, types, idgen,
-  tables
+  tables, docgen2
 
 const
   has_LLVM_Backend = false
@@ -103,6 +103,14 @@ proc CommandCheck =
   registerPass(rodwrite.rodwritePass())
   compileProject(mainCommandArg())
 
+proc CommandDoc2 =
+  msgs.gErrorMax = high(int)  # do not stop after first error
+  semanticPasses()
+  registerPass(docgen2Pass())
+  registerPass(cleanupPass())
+  compileProject(mainCommandArg())
+  finishDoc2Pass(gProjectFull)
+
 proc CommandCompileToC =
   semanticPasses()
   registerPass(cgen.cgenPass())
@@ -232,6 +240,11 @@ proc MainCommand =
     LoadConfigs(DocConfig)
     wantMainModule()
     CommandDoc()
+  of "doc2":
+    gCmd = cmdDoc
+    LoadConfigs(DocConfig)
+    wantMainModule()
+    CommandDoc2()
   of "rst2html": 
     gCmd = cmdRst2html
     LoadConfigs(DocConfig)

doc/advopt.txt

@@ -2,6 +2,7 @@ Advanced commands:
   //compileToC, cc          compile project with C code generator
   //compileToCpp, cpp       compile project to C++ code
   //compileToOC, objc       compile project to Objective C code
+  //doc2                    generate the documentation for the project
   //rst2html                convert a reStructuredText file to HTML
   //rst2tex                 convert a reStructuredText file to TeX
   //buildIndex              build an index for the whole documentation

todo.txt

@@ -1,6 +1,8 @@
 version 0.9.0
 =============
 
+- test new doc2 generator
+
 Debug GC session:
 - bug: stress testing basic method example (eval example) 
   without ``-d:release`` leaks memory?
@@ -13,7 +15,6 @@ New pragmas:
 - ``borrow`` needs to take type classes into account
 - make templates hygienic by default: try to gensym() everything in the 'block'
   of a template; find a better solution for gensym instead of `*ident`
-- ``bind`` for overloaded symbols does not work apparently
 - ``=`` should be overloadable; requires specialization for ``=``
 - fix remaining closure bugs:
   - make toplevel but in a scope vars local; make procs there inner procs
@@ -25,7 +26,7 @@ New pragmas:
 - unsigned ints and bignums; requires abstract integer literal type: 
   use tyInt+node for that
 - change how comments are part of the AST
-- extract nimdoc properly and document it finally
+- document nimdoc properly finally
 - rethink the syntax: distinction between expr and stmt is unfortunate; 
   indentation handling is quite complex too; problem with exception handling
   is that often the scope of ``try`` is wrong and apart from that ``try`` is
@@ -105,8 +106,7 @@ Low priority
 
 - ``with proc `+`(x, y: T): T`` for generic code
 - new feature: ``distinct T with operations``
-- find a way for easy constructors and destructors; (destructors are much more
-  important than constructors)
+- implement the "easy" constructors idea; document destructors
 - code generated for type information is wasteful
 - resizing of strings/sequences could take into account the memory that
   is allocated

web/news.txt

@@ -100,7 +100,8 @@ Compiler Additions
   option or pragma.
 - The compiler now generates marker procs that the GC can use instead of RTTI.
   This speeds up the GC quite a bit.
-- The compiler now supports OpenMP's parallel for loop.
+- The compiler now includes a new advanced documentation generator 
+  via ``doc2``.
 
 
 Language Additions