On Thu, 6 Nov 2014 17:52:05 +1000 David Seikel <[email protected]> said:
> On Thu, 6 Nov 2014 16:09:26 +0900 Carsten Haitzler (The Rasterman) > <[email protected]> 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. > > The project has my permission to change the license of what ever > documentation bits I wrote to BDS or CCC, or something similar. I was > generally assuming BSD for the docs, since that covers most of EFL. > > > 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? > > > > So basically you want a wiki with discussion, and where the content can > be managed via git. Gollum seems to be missing any sort of discussion > feature from a quick look. Is there a plugin? correct - it doesn't have discussion stuff. i don't know of a plugin. haven't looked. > Somehow we would need to convert the current doxygen to what ever this > wiki system uses. At a quick look I can't see any formats doxygen and > gollum share. actually we'd generate direct from .eo files. we generate .h files with docs FROM .eo files for a large amount of our current docs/apis. this would generate them for us form eo files ultimately with no docs in the eo files themselves. at least initially i would expect it to copy over the doxy stuff "verbatim" and then we strip out the doxy stuff from eo files. from other .h files - we'd have to move things to be eo classes first i think for a lot except eina... (and eo itself). these would go over manually or someone make a script to do it... ? > As you mentioned, we would need a Python coder, and maybe Ruby ones as > well. Do we have any? Personally I have an unreasonable hatred of any > programming language beginning with the letter "P", and Ruby is an > honorary member of that group. I have coded in Python a little bit > though. we have no shortage of pythoners. :) > Drupal is how I would normally go about setting up such things. Dunno > if there's any drupal module for driving content via git, but I suspect > there is. I've created wiki's with discussion threads using Drupal, > that's what I use for my own stuff. Yes, it's PHP, yes I've written > Drupal modules in PHP, yes PHP still sucks. Doxygen can output HTML, > which could be fed to Drupal via filters. but the back-end of drupal is... a bunch of sql - right? that makes it horrible already from the get go. -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) [email protected] ------------------------------------------------------------------------------ _______________________________________________ enlightenment-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
