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