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 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. :) 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? -- 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
