# packages/docutils/dochelpers

Theme:

- Manual
- Standard library
- Index
- Compiler docs
- Fusion docs
- devel, stable

Search:
Source Edit

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, assertions, syncio

# 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