On Wed, 12 Nov 2014 19:09:33 -0800 Jeff Grimshaw <jeffrey.w.grims...@gmail.com> wrote:
> I've been doing some research around getting docs to work in Phab's > Diviner application. I've got a local Phab running, which was pretty > easy to do. Diviner doesn't look too bad, but still some work. The > good news is that it already supports some of the features folks have > been talking about, like syntax highlighting via Pygments! :-) Also > supports linking to repos, tasks, wikis and other Phab objects. No > discussions though. > > So the way I think about docs, there are 3 flavors: expository > (guides, tutorials, other hand written stuff), examples (runnable > code) and API reference. Expository docs are the easy part, since we > can just write and maintain those in markdown or some other > lightweight formatting language. In Diviner, these would be *.diviner > files written in ReMarkup, similar to how we have *.dox files today. > Examples are likewise simple since they are just commented code. We > might have an accompanying *.diviner file that gives a deeper > explanation with code snippets taken from the example and links back > to the full source file. > > The difficult bit is the API reference. I'll assume we want to > auto-gen from Doxygen comments. There are other ways t do this, but > let's assume generated API ref for now. The way it's done in Diviner > is similar to other tools like Doxygen. There are flex/bison > programs that lex/parse files (just php now) and output a sort of AST > that has the interesting bits in it. I think I could make that work > in Diviner for C/C++/Doxygen by making new flex and bison programs, > then creating a new atomizer that operates on that AST. I have no > idea how long that will take. I haven't done PHP or flex or bison > before, so this should be fun! You might want to try lemon instead of bison. Some of us have experience with it, and there's even some source code in our git. I find it a bit easier to work with. > I'll also run this past the Phab folks and see if anyone else is > working on it. > > I've been thinking about workflow for docs too, but more on that > later. Dinner is on the table! > > On Tue, Nov 11, 2014 at 1:39 AM, Thanatermesis > <thanatermesis.e...@gmail.com > > wrote: > > > For a Forum I was recently looking at the "discourse" one and I was > > thinking to move the actual forum of Elive to it > > http://www.discourse.org/ , Btw yesterday somebody tried to give a > > feedback about e18/e19+ but didn't found easly "where is" the > > mailing list (or if there is any) > > > > About the documentation, what about having a git hook in the server > > that rejects any commit that modified (or added) code without its > > relative documentation ? we can make a simple parser for this or > > use the "documentation tools" to parse the specific commited parts, > > we could even use specific keywords for that. On this way there > > will be no way to push a fast commit if the documentation is not > > 100% updated > > > > > > 2014-11-10 8:38 GMT+01:00 Lionel Orry <lionel.o...@gmail.com>: > > > > > Hello devs, > > > > > > On Thu, Nov 6, 2014 at 8:09 AM, Carsten Haitzler > > > <ras...@rasterman.com> wrote: > > > > i thought i'd start this here for a wide audience. > > > > > > > > documentation for efl. it's rather horrible. and yesterday it > > > > dawned on > > > me... > > > > it has license problems too. > > > > > > > > 1. license problems: > > > > > > > > the documentation in many parts is lgpl - and that means > > > > copying any > > > code from > > > > code snippets or examples in the docs makes the app you copy it > > > > into > > > lgpl. that > > > > is BAD. enforcing the license even though with lgpl we intend > > > > the > > library > > > > boundary to be the library itself. we can add exceptions, but > > > > splitting > > > docs > > > > out might actually be best. reality is that no one is ever > > > > going to sue > > > over > > > > this and it's safe as it's not intended to be a problem, but > > > strictly/legally > > > > it is. if someone has a legal department that really dots their > > > > i's and > > > crosses > > > > their t's... they would spot this. > > > > > > > > 2. our docs are a mess. a lot are not linked to and > > > > undiscoverable. > > they > > > have > > > > typos, missing docs - often are sparse and with little or > > > > nothing in > > the > > > way of > > > > binding things together. they are at best a very slim reference > > > > set for > > > apis > > > > with little besides that. some references are good, but most > > > > are also > > > very > > > > thin. keeping docs totally in the hands of core devs (always in > > > > the > > > source > > > > tree - src commit access needed) simply is *NOT WORKING*. devs > > > > work on > > > code. we > > > > just are not doing docs. we should do them, but reality is we > > > > are not > > > and have > > > > little incentive to do it. core devs are busy enough as-is. > > > > > > > > 3. eo brings the added problem of needing docs to cover multiple > > > languages > > > > from a single source. C, C++, Lua, JS, Python... it's a unique > > > > problem > > > that > > > > using doxygen is never going to solve. we need a solution. i > > > > haven't > > > found > > > > another solution and to be honest ours will be custom due to > > > > eo/eolian > > > anwyay. > > > > > > I never used it myself but I heard some positive feedbacks about > > > Dexy : http://dexy.it > > > I also know it includes a markdown parser (have I read markdown > > > somewhere in that thread?) > > > > > > Have a look we never know. I'te been used on mongrel2 which is > > > made in C and also makes use of pyhon for handlers, so both > > > languages are supported. > > > > > > > > > > > 4. people ask questions on efl all the time and we answer in > > > > email, irc > > > etc. .. > > > > and this information is not captured. it's lost. that's because > > > > there > > is > > > no > > > > "forum" for asking such q's. we should closely tie such forums > > > > and q&a > > to > > > > documentation. this would massively improve the value of docs. > > > > > > > > 5. the theory of keeping docs with the code is just not > > > > working. it > > > doesn't > > > > encourage them to be good. it just isn't working - plain and > > > > simple. > > > it's time > > > > to re-evaluate that. > > > > > > > > ... > > > > > > > > we need a solution. we need to expand the set of peole who can > > > contribute to > > > > documentation. we need to handle multiple languages with a > > > > single > > > source. we > > > > need to collect q&a together with the docs that are relevant. > > > > we need > > to > > > > encourage our docs not to fragment. > > > > > > > > what i propose is we take a long hard look at how we document > > > > and > > > present docs > > > > to the world. i'm opening this up to people to contribute to the > > > discussion and > > > > propose solutions and share their knowledge/experience. let me > > > > start: > > > > > > > > 1. we set up a wiki that is easy to drive from a back-end in > > > > terms of > > > inserting > > > > content. jpeg has spent a fair bit of time looking at gollum. > > > > gollum > > > looks good: > > > > https://github.com/gollum/gollum - it is a wiki that is all > > > > plain text > > > files > > > > (hooray! no danged db) in a directory tree... with everything > > > > in git. > > > that means > > > > you can edit the wiki with your fave text editor and git > > > > commit/push > > your > > > > changes. web interface is not needed - but is there for those > > > > without > > > back-end > > > > git access. we can automate inserting content with scripts too > > > > and so > > > life gets > > > > easy for automated infra. that is good. > > > > > > > > 2. we need to solve discussions. being able to have a thread on > > > > any > > wiki > > > page > > > > would really help. like reddit or any of these places, we would > > > > have a > > > live > > > > community of people discussing things. they can discuss on the > > > > page > > that > > > is > > > > relevant. it'd be nice if someone proposes a way to do this > > > > with gollum > > > or has > > > > a solution that already does this that is as nice as gollum is? > > > > > > > > 3. we write scripts (maybe lua? since we already have lualian > > > > using > > > eolian libs > > > > from lua) that use eolian and parse eo files and GENERATE the > > > > template documentation markdown pages from our eo classes. they > > > > only generate > > > EMPTY > > > > templates with func prototypes, enums, structs etc. only > > > > generate them > > > when a > > > > new class or method/property/event is added. these pages then > > > > are > > filled > > > in via > > > > the documentation git repo/wiki etc. and can be edited over > > > > time and > > > improved. > > > > > > > > 4. this documentation now has a more acceptable license - maybe > > creative > > > commons > > > > or bsd-2-clause? be explicit on it. > > > > > > > > 5. we just re-run the generation scripts every efl release so > > > > new > > things > > > we > > > > added get templates. maybe when we begin release > > > > freeze/stabilization > > to > > > make > > > > this period a documentation effort too. the scripts can even > > > > generate > > > pages > > > > that give status on how much is or is not documented yet, > > > > giving a > > > quality > > > > measure so we can strive to get that to 100%. dont overwrite > > > > pages > > > already > > > > there as they may have changes in them. by generating current > > > > status, > > > it's a > > > > score that "gameifies" documentation. you want 100% of pages > > > > that are > > > auto > > > > generated that should then be filled to have at least 1 commit > > > > after > > the > > > intial > > > > insert into the repo. that gets your % coverage. then you get > > > > bonus > > > points for > > > > how much extra documentation there is (size of these files lets > > > > say in > > > bytes as > > > > a quick and dirty measure of doc points). > > > > > > > > 6. as it's git - we can revert any doc changes we see are > > inappropriate - > > > > easily. git revert. yay. we also get emails on commits so we > > > > know > > what's > > > going > > > > on. > > > > > > > > 7. when we generate, we generate docs in sections. you generate > > > > the > > > "core" docs > > > > (gollum supports markdown that lets you "#include" other > > > > markdown > > pages) > > > per > > > > language we support, and then specific markdown is generic > > > > (include > > that > > > into > > > > the master page for that class, method, event generated for that > > > language), > > > > with the rest of that page being language specific. thus every > > > > class > > and > > > method, > > > > event generates a skeleton per language, as well as a generic > > > > "core" > > > markdown > > > > that is included into the skeleton. this should support multiple > > > languages > > > > nicely. the generation also ensures that symbols are linked to > > > > the > > right > > > > markdown pages automatically. so you end up with something like: > > > > > > > > timer/ > > > > timer/C_class.md -> "#include class.md + #include > > > > class_inherits.md > > ..." > > > > timer/LUA_class.md -> "#include class.md + ..." > > > > timer/CPP_class.md -> "#include class.md + ..." > > > > timer/JS_class.md -> "#include class.md + ..." > > > > timer/PY_class.md -> "#include class.md + ..." > > > > timer/class.md > > > > timer/class_inherits.md > > > > timer/class_contents.md > > > > ... > > > > timer/funcs/C_method1.md > > > > timer/funcs/LUA_method1.md > > > > timer/funcs/CPP_method1.md > > > > ... > > > > timer/funcs/method1.md > > > > ... > > > > timer/events/C_callback1.md > > > > timer/events/LUA_callback1.md > > > > ... > > > > timer/events/callback1.md > > > > > > > > you get the idea (ok have some more auto generated files that > > > > are > > > included too > > > > most likely - like classes that are inherited for this class > > > > the actual > > > list > > > > of funcs, properties and callbacks (including overridden ones > > > > that are > > > marked > > > > as such)). > > > > > > > > same per func/method/property/event - generate the lan specific > > > prototypes and > > > > "#include" the core docs, then you can put lang specifics per > > > > generated > > > file if > > > > need be (or just edit class.md) > > > > > > > > 8. gollum uses pygments for code highlighting. it can #include > > c/h/js/py > > > files > > > > etc. and color highlight them via pygments. we'd have to teach > > > > pygments about .eo syntax i think - maybe edc. we can cheat and > > > > use C highlights > > > for > > > > now. but what does need doing is ensuring pygments can generate > > > > LINKS > > to > > > the > > > > right markdown pages in the docs. the doc generator will need to > > > generate some > > > > kind of index of symbol -> markdown page address so pygments > > > > can create > > > the > > > > correct link when generating the colorized output when it sees a > > matching > > > > symbol. someone willing to do the python work here would be > > > > needed. but > > > the > > > > nice thing is we can "#include" the c src for docs .. keeping > > > > the > > > original src > > > > in separate files .. thus keeping them compileable! :) > > > > > > > > this is a start - what do people have to add/say? > > > > > > > > do you have something ... better? can you improve the above? > > > > > > > > -- > > > > ------------- Codito, ergo sum - "I code, therefore I am" > > -------------- > > > > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > > > > > > > > > > > > > > > > ------------------------------------------------------------------------------ > > > > _______________________________________________ > > > > enlightenment-devel mailing list > > > > enlightenment-devel@lists.sourceforge.net > > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > > Cheers, > > > Lionel > > > > > > > > > > > ------------------------------------------------------------------------------ > > > _______________________________________________ > > > enlightenment-devel mailing list > > > enlightenment-devel@lists.sourceforge.net > > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > > > ------------------------------------------------------------------------------ > > Comprehensive Server Monitoring with Site24x7. > > Monitor 10 servers for $9/Month. > > Get alerted through email, SMS, voice calls or mobile push > > notifications. Take corrective actions from your mobile device. > > > > http://pubads.g.doubleclick.net/gampad/clk?id=154624111&iu=/4140/ostg.clktrk > > _______________________________________________ > > enlightenment-devel mailing list > > enlightenment-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > > > > -- A big old stinking pile of genius that no one wants coz there are too many silver coated monkeys in the world.
signature.asc
Description: PGP signature
------------------------------------------------------------------------------ Comprehensive Server Monitoring with Site24x7. Monitor 10 servers for $9/Month. Get alerted through email, SMS, voice calls or mobile push notifications. Take corrective actions from your mobile device. http://pubads.g.doubleclick.net/gampad/clk?id=154624111&iu=/4140/ostg.clktrk
_______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
