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
