Docs generator

[garritfra]

As discussed in the group, we'd like to have a html generator for code documentation.

An example documentation would look like his:

---
@doc 
# This function converts x to y
Lorem ipsum
[Markdown links!](https://foo.bar/)

@param a number to convert
@returns converted string
---
fn foo x:
  x -> toY

Important to note, is that the three dashes (---) represent a block comment. If a @doc symbol is present in this comment, it will be treated as documentation. README.md files either in project root or in modules will be included in the documentation

Running clio docs should compile the docs and put the generated html into the root/docs directory. It should be possible to write markdown inside of the documentation, that will be compiled to html. Possibly, a --open flag could be passed, which opens the generated docs in your browser.

A possible solution would be, to compile the Clio documentation to javascript and use jsdoc, however, further research is to be done about markdown parsing.

In order to begin working on this issue, #24 needs to be completed.

Room for discussion

• Somehow open the local documentation for clio itself, instead of showing the docs for the current package.
• In the future, we could maybe add manpage-like docs, like clio docs flow, which will point to the documentation for the flow operator.

Criteria

• Multiline comments that include @doc are treated as documentation
• Running clio docs generates the docs as html
• Docs support markdown
• Compiled documentation lives in root/docs
• README.md files are included
• clio docs --open opens the generated docs in a browser

[pouya-eghbali]

I added multiline + nested comments in the new version, syntax is a little bit different:

+-
@doc 
# This function converts x to y
Lorem ipsum
[Markdown links!](https://foo.bar/)

@param a number to convert
@returns converted string
-+
fn foo x:
  x -> toY

[pouya-eghbali]

Comments are now in parse tree (v0.4), and are attached to functions and viewable using man function:

man add

However, we're not generating any docs yet.

[pouya-eghbali]

I've added a command for displaying the man[uals] in the terminal:

clio-man-improved.mov

This will be in 0.7