On Thu, 6 Nov 2014 19:17:55 +0900 Carsten Haitzler (The Rasterman) <ras...@rasterman.com> wrote:
> On Thu, 6 Nov 2014 19:18:39 +1000 David Seikel <onef...@gmail.com> > said: > > > On Thu, 6 Nov 2014 17:20:33 +0900 Carsten Haitzler (The Rasterman) > > <ras...@rasterman.com> wrote: > > > > > On Thu, 6 Nov 2014 17:52:05 +1000 David Seikel <onef...@gmail.com> > > > said: > > > > > > > On Thu, 6 Nov 2014 16:09:26 +0900 Carsten Haitzler (The > > > > Rasterman) <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. > > > > > > > > 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 trmanhem, 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. :) > > > > Phew, I dodged that bullet. B-) > > > > > > 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. > > > > Most of this sort of software is backed by an SQL database, though > > some even work with NoSQL databases. Though not everything is > > stored in a database. There's a certain amount of flexibility as > > well, content can be from outside the database. Do you object to > > any sort of database at all, and why? > > the core content .. 99.9% of it will be markdown wiki pages. if this > "content outside of database" is outside of the wiki (cant edit from > wiki web ui - only stuff thats within the db can be edited), then it > makes it a non-starter as we cant do simple maintenance of the whole > doc tree. If we can't find pre written modules, or a whole other complete package, then it might come down to - which is an easier module to write, discussion features, or file backend for content? I'd guess the later for most modular wiki / CMS systems. -- 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
------------------------------------------------------------------------------
_______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
