docgen

Source Edit

This is the Nim documentation generator. Cross-references are generated by knowing how the anchors are going to be named.

For corresponding users' documentation see Nim DocGen Tools Guide.

Imports

ast, options, msgs, idents, wordrecg, syntaxes, renderer, lexer, trees, types, typesrenderer, astalgo, lineinfos, pathutils, nimpaths, renderverbatim, packages, nodejs

Types

PDoc = ref TDocumentor

Alias to type less. Source Edit

Procs

proc commandBuildIndex(conf: ConfigRef; dir: string; outFile = RelativeFile"") {....raises: [
    OSError, IOError, ValueError, Exception, Exception, ValueError, KeyError,
    OSError, IOError, ERecoverableError], tags: [ReadDirEffect, ReadIOEffect,
    RootEffect, ReadEnvEffect, TimeEffect, WriteIOEffect], forbids: [].}

Source Edit

proc commandBuildIndexJson(conf: ConfigRef; dir: string;
                           outFile = RelativeFile"") {....raises: [OSError,
    IOError, ValueError, Exception, ValueError, KeyError, OSError, IOError,
    ERecoverableError], tags: [ReadDirEffect, ReadIOEffect, WriteIOEffect,
                               RootEffect, ReadEnvEffect], forbids: [].}

Source Edit

proc commandDoc(cache: IdentCache; conf: ConfigRef) {....raises: [OSError,
    Exception, ValueError, KeyError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect, ExecIOEffect, TimeEffect], forbids: [].}

implementation of deprecated doc0 command (without semantic checking) Source Edit

proc commandJson(cache: IdentCache; conf: ConfigRef) {....raises: [Exception,
    ValueError, KeyError, OSError, IOError, ERecoverableError, Exception,
    ValueError, KeyError, OSError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect], forbids: [].}

implementation of a deprecated jsondoc0 command Source Edit

proc commandRst2Html(cache: IdentCache; conf: ConfigRef; preferMarkdown = false) {....raises: [
    OSError, IOError, Exception, KeyError, ValueError, ERecoverableError], tags: [
    WriteDirEffect, ReadDirEffect, RootEffect, WriteIOEffect, ReadIOEffect,
    ReadEnvEffect, ExecIOEffect, TimeEffect], forbids: [].}

Source Edit

proc commandRst2TeX(cache: IdentCache; conf: ConfigRef; preferMarkdown = false) {....raises: [
    OSError, IOError, Exception, KeyError, ValueError, ERecoverableError], tags: [
    WriteDirEffect, ReadDirEffect, RootEffect, WriteIOEffect, ReadIOEffect,
    ReadEnvEffect, ExecIOEffect, TimeEffect], forbids: [].}

Source Edit

proc commandTags(cache: IdentCache; conf: ConfigRef) {....raises: [Exception,
    ValueError, KeyError, OSError, IOError, ERecoverableError, Exception,
    ValueError, KeyError, OSError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect], forbids: [].}

Source Edit

proc documentRaises(cache: IdentCache; n: PNode) {.
    ...raises: [Exception, KeyError, ValueError], tags: [RootEffect], forbids: [].}

Source Edit

proc finishGenerateDoc(d: var PDoc) {....raises: [Exception, ValueError, KeyError,
    OSError], tags: [RootEffect, ReadIOEffect, ReadDirEffect, ReadEnvEffect],
                                      forbids: [].}

Perform 2nd RST pass for resolution of links/footnotes/headings... Source Edit

proc generateDoc(d: PDoc; n, orig: PNode; config: ConfigRef;
                 docFlags: DocFlags = kDefault) {....raises: [ValueError,
    Exception, KeyError, OSError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect], forbids: [].}

Goes through nim nodes recursively and collects doc comments. Main function for doc command, which is implemented in docgen2.nim. Source Edit

proc generateIndex(d: PDoc) {....raises: [OSError, Exception, KeyError, ValueError,
                                       IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect], forbids: [].}

Source Edit

proc generateJson(d: PDoc; n: PNode; config: ConfigRef;
                  includeComments: bool = true) {....raises: [Exception,
    ValueError, KeyError, OSError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect], forbids: [].}

Source Edit

proc generateTags(d: PDoc; n: PNode; r: var string) {.
    ...raises: [KeyError, Exception, ValueError], tags: [RootEffect], forbids: [].}

Source Edit

proc handleDocOutputOptions(conf: ConfigRef) {....raises: [OSError], tags: [],
    forbids: [].}

Source Edit

proc newDocumentor(filename: AbsoluteFile; cache: IdentCache; conf: ConfigRef;
                   outExt: string = HtmlExt; module: PSym = nil;
                   standaloneDoc = false; preferMarkdown = true; hasToc = true): PDoc {....raises: [
    OSError, IOError, Exception, KeyError, ValueError, ERecoverableError], tags: [
    WriteDirEffect, ReadDirEffect, RootEffect, WriteIOEffect, ReadIOEffect,
    ReadEnvEffect], forbids: [].}

Source Edit

proc presentationPath(conf: ConfigRef; file: AbsoluteFile): RelativeFile {....raises: [
    Exception, KeyError, OSError, ValueError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect],
    forbids: [].}

returns a relative file that will be appended to outDir Source Edit

proc writeOutput(d: PDoc; useWarning = false; groupedToc = false) {....raises: [
    Exception, OSError, KeyError, ValueError, IOError, ERecoverableError,
    Exception, ValueError, KeyError, OSError, IOError, ERecoverableError], tags: [
    RootEffect, ReadDirEffect, WriteIOEffect, ReadIOEffect, ReadEnvEffect,
    WriteDirEffect, ExecIOEffect, TimeEffect], forbids: [].}

Source Edit

proc writeOutputJson(d: PDoc; useWarning = false) {....raises: [OSError,
    ValueError, IOError, Exception, KeyError, ERecoverableError], tags: [
    ReadEnvEffect, ReadIOEffect, WriteIOEffect, ReadDirEffect, ExecIOEffect,
    RootEffect, WriteDirEffect], forbids: [].}

Source Edit