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
