liquidev / euwren

High-level Wren wrapper for Nim
MIT License
36 stars 0 forks source link

Documentation generator #15

Open liquidev opened 4 years ago

liquidev commented 4 years ago

It would be nice to have a doc generator for euwren modules. Syntax example:

import macros, os
const Docs = getProjectPath()/"docs"

wren.foreign("myModule"):
  # output is markdown for easy piping to pandoc or other renderers
  # (open to consideration, may use html or rst in the end)
  {.doc: Docs/"myModule.md".}
  MyClass:
    ## This class implements some methods.
    sayHello # doc comment is inherited from the proc
    printNumber ## This proc prints a number.
    # ↑ doc comment is specified explicitly
    *newMyClass -> new
    ?someField

Example of generated output:

## module `myModule`

### index
 - class `MyClass` (with a link to the class)

### class `MyClass`

#### `sayHello()`

Prints hello to the console.

#### `printNumber(x: number)`

This proc prints a number.

#### static `new()`

> no documentation provided

#### `someField`

> no documentation provided

A macro specifying generation options could be provided.

euwren.docOpt:
  format = "html"
  stylesheet = slurp("docStyle.css")
  # etc