clio
clio copied to clipboard
Docs generator
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, likeclio 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
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
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.
I've added a command for displaying the man[uals] in the terminal:
https://user-images.githubusercontent.com/4604055/119242665-18aa4a80-bb60-11eb-8475-0548b34be585.mov
This will be in 0.7