On Fri, Jan 13, 2012 at 1:14 PM, Uli Schlachter <psyc...@znc.in> wrote: > On 11.01.2012 14:30, Anurag Priyam wrote: >> I am not sure how exactly to proceed, but here is the general idea: [...] >> * figure out how to integrate into awesome's build system > > > This last step can be skipped. I'd volunteer for integrating this with cmake > (and all other parts which dont have to be done immediately and are > annoying).
Cool. Thanks :). >> 2. See if luadoc supports custom templates >> >> * choose, or write (this will be painful; I suck at design) one for >> Awesome, to be used at https://awesome.naquadah.org/doc/api/ > > JD, do you want to make a webpage? If luadoc supports templates, it should be pretty easy. The inspiration for me, here, are the documentation tools in Ruby. Particularly, [Yard][1]. See the following page for example, created with Yard for one of my projects: http://rubydoc.info/github/yannickwurm/sequenceserver/frames Looks elegant and is even searchable. Though I never dug into Yard to see how the searching is implemented. Not sure if luadoc can do it, and if it is worth implementing it. These are the sort of ideas I meant for step 3 (other goodies) later. >> I definitely can't work on this before 21st of Jan. Probably not till >> Jan end actually. But, if anyone finds this particularly interesting, >> and have time, please, by all means, go ahead with it. I will join >> hands as soon as I can find time. I have put up a clone of awesome on Github: http://github.com/yeban/awesome. So you can easily track when I am on it. > I might have time from march 1st for two weeks (then I'll be offline for a > while)... Hmm. > I certainly wouldn't miss luadoc syntax. I wouldn't miss luadoc either. I > once managed to break luadoc and then had to figure out from the lua error > which documentation bit was wrong. Urgh. Luadoc doesn't go away; we leverage it. > Besides that, I have to admit that I don't test the luadoc documentation (= > I don't have luadoc installed and thus wouldn't notice if it errors out). Wow! :P > However, I have some questions: > How do you intend to use markdown from lua? Is there a lua-markdown library > which is even less common than luadoc? There is lua-discount which is a Lua wrapper over the Discount markdown library in C. I had mentioned it in the previos > Also, why markdown? It is nice for e.g. writing webpages, but for > documentation it misses stuff like @param. So if everyone comes up with his > own syntaxes for function arguments, return values, etc then this might come > out messy. Luadoc semantics still apply. From what I understand, luadoc parses the comments in a given source file and converts it into an internal structure (sort of like an object model) first. Next, you process this internal structure to produce final HTML output. This is where Markdown steps in. You can customize both the steps by defining custom tags and output generator respectively. See http://keplerproject.github.com/luadoc/architecture.html. I am hoping that I will be able to convert this internal representation into something directly consumable by lua-discount. [1]: http://yardoc.org/ -- Anurag Priyam -- To unsubscribe, send mail to awesome-devel-unsubscr...@naquadah.org.
