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