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. 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
