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
As discussed in the group, we'd like to have a html generator for code documentation.
An example documentation would look like his:
Important to note, is that the three dashes (
---) represent a block comment. If a@docsymbol is present in this comment, it will be treated as documentation.README.mdfiles either in project root or in modules will be included in the documentationRunning
clio docsshould compile the docs and put the generated html into theroot/docsdirectory. It should be possible to write markdown inside of the documentation, that will be compiled to html. Possibly, a--openflag 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
manpage-like docs, likeclio docs flow, which will point to the documentation for the flow operator.Criteria
@docare treated as documentationclio docsgenerates the docs as htmlroot/docsREADME.mdfiles are includedclio docs --openopens the generated docs in a browser