packages/docutils/dochelpers

Integration helpers between docgen.nim and rst.nim.

Function toLangSymbol(linkText) produces a signature docLink of type LangSymbol in rst.nim, while match(generated, docLink) matches it with generated, produced from PNode by docgen.rst.

Imports

rstast, strutils

Types

LangSymbol = object
  symKind*: string           ## "proc", "const", "type", etc
  symTypeKind*: string       ## ""|enum|object|tuple -
                             ## valid only when `symKind == "type"`
  name*: string              ## plain symbol name without any parameters
  generics*: string          ## generic parameters (without brackets)
  isGroup*: bool             ## is LangSymbol a group with overloads?
  parametersProvided*: bool  ## to disambiguate `proc f`_ and `proc f()`_
  parameters*: seq[tuple[name: string, `type`: string]] ## name-type seq, e.g. for proc
  outType*: string           ## result type, e.g. for proc

symbol signature in Nim Source Edit

Procs

proc `$`(s: LangSymbol): string {....raises: [ValueError], tags: [], forbids: [].}

Source Edit

proc langSymbolGroup(kind: string; name: string): LangSymbol {.
    ...raises: [ValueError], tags: [], forbids: [].}

Source Edit

proc match(generated: LangSymbol; docLink: LangSymbol): bool {....raises: [],
    tags: [], forbids: [].}

Returns true if generated can be a target for docLink. If generated is an overload group then only symKind and name are compared for success. Source Edit

func nimIdentBackticksNormalize(s: string): string {....raises: [], tags: [],
    forbids: [].}

Normalizes the string s as a Nim identifier.

Unlike nimIdentNormalize removes spaces and backticks.

Warning: No checking (e.g. that identifiers cannot start from digits or '_', or that number of backticks is even) is performed.

Example:

doAssert nimIdentBackticksNormalize("Foo_bar") == "Foobar"
doAssert nimIdentBackticksNormalize("FoO BAr") == "Foobar"
doAssert nimIdentBackticksNormalize("`Foo BAR`") == "Foobar"
doAssert nimIdentBackticksNormalize("` Foo BAR `") == "Foobar"
# not a valid identifier:
doAssert nimIdentBackticksNormalize("`_x_y`") == "_xy"

Source Edit

proc toLangSymbol(linkText: PRstNode): LangSymbol {....raises: [ValueError],
    tags: [], forbids: [].}

Parses linkText into a more structured form using a state machine.

This proc is designed to allow link syntax with operators even without escaped backticks inside:

`proc *`_
`proc []`_

This proc should be kept in sync with the renderTypes proc from compiler/typesrenderer.nim.

Source Edit