On Fri, 3 Apr 2015 10:28:30 +0200 Lionel Orry <lionel.o...@gmail.com> said:
> On Fri, Apr 3, 2015 at 4:22 AM, Carsten Haitzler <ras...@rasterman.com> wrote: > > On Thu, 02 Apr 2015 16:20:38 +0200 Jonathan Aquilina > > <jaquil...@eagleeyet.net> said: > > > >> Not working in what sense? I would be up for looking into the issues and > >> getting things working with proper documentation through doxygen. Since > >> my programming know how that is needed for E is non existent. > > > > make doc (run a doxygen build run) across efl and elm take like ~2-5mins ... > > thats about as long - even longer than compiling efl and elementary. > > doxygen has to do a FULL rebuild. it can't do a partial. that means > > turn-around time between you edited docs in src and seeing what they come > > out as is way too long. it should be no more than a few seconds. > > > > the docs somehow end up with mountains of the docs simply inaccessible. they > > are there but unlinked from master pages so navigating to them is basically > > impossible - and fixing it as above is a journey in such frustration that > > you give up. > > > > i dislike that doxygen just splats everything in a class (group) and all > > api's on a single page ... in whatever order it feels like. long ago in the > > early days of evas - back in 2001 or so i wrote a 200 page document on al > > of evas. i put 1 api call per page. it was neater and people actually liked > > the docs. never since has anyone liked the doxygen docs. > > > > the styling is ... bad. and hard to improve and customize further. > > > > no idea how to make doxygen properly link elm and efl docs - so when you > > have evas_object_del() in elm docs - it points to the efl docs. it just is > > totally unlinked as the doc build is separate from efl. without a src tree > > merge i just don't see this working. also as long as doc builds are part of > > src - they are separate entites but efl is seen as efl + elementary by > > develoeprs and they complain bitterly if our docs are not unified as a > > single entity. in fact all our existing efl docs pretty much assume ecore > > is separate to eina is separate to evas is separate to ecore_evas is > > separate to edje etc because that is just how they always have been. it's > > time we stop that because people just don't like it. > > > > doxygen doesn't understand eo. it can't. it doesn't understand OO in C. it > > doesn't grok eo inheritance. we would have to fake generate pretend oo docs > > for C (some .h files with groups pretending to be classes, and hand-done > > comments and links on inheritance). it also doesn't understand events > > within our eo oo setup - that objects inherit events from parent classes. > > > > That makes me think... The entity who knows best Eo is Eolian. I think > eolian should be made more versatile and have a larger set of > generators, not only C and C++ (using eina modules maybe ?); one of > them could be a Markdown generator, so that eolian generates the > source code and the doc at the same time! we do. there is a javascript one in one of the efl git branches (v8/node.js) and there is a lua one too in git master. work has been done to get a python one going as well (status unknown atm). :) at least the idea for now is libeolian woul dbe used to parse the eo files and then spit out whatever is needed as the parsing is then done and all in memory - maybe use lua to do it. > It surely needs quite some work on eolian but I believe since the > parser / lexer are already in, that could be worth it. > > > and frankly developers simply aren't writing docs. if we keep docs in src > > then only devs can write them, and devs don't, so we will NEVER have > > docs .. by definition. i want to split docs out from the src in a way that > > means we don't have long build times. so dedicated tech > > writers/documentation people can easily work on them. it won't be hard to > > make tools to import markdown templates from the .eo files and thus add new > > classes, events, methods as they appear (with empty docs), then to be > > filled in with fast feedback. > > > >> --- > >> Regards, > >> Jonathan Aquilina > >> Founder Eagle Eye T > >> > >> On 2015-04-02 11:11, Carsten Haitzler wrote: > >> > >> > On Thu, 02 Apr 2015 07:53:15 +0200 Jonathan Aquilina > >> > <jaquil...@eagleeyet.net> said: > >> > > >> >> Hey Jeff and everyone, You guys mention the API why not take a look at > >> >> doxygen. http://www.stack.nl/~dimitri/doxygen/ [1] It allows you to > >> >> annotate with special doxygen specific syntax and supports multiple > >> >> languages. This will then easily generate the documentation for you. > >> > > >> > we have been using doxygen for years now... and it just isnt working for > >> > us. (final assessment - lots of details). time to try something new. > >> > --- Regards, Jonathan Aquilina Founder Eagle Eye T On 2015-04-02 07:49, > >> > Jeff Grimshaw wrote: On Wed, Apr 1, 2015 at 8:21 PM, Carsten Haitzler > >> > <ras...@rasterman.com> wrote: On Wed, 01 Apr 2015 22:19:53 +0100 Bertrand > >> > Jacquin <bertr...@jacquin.bzh> said: On 31/03/2015 23:46, Carsten > >> > Haitzler wrote: On Tue, 31 Mar 2015 17:33:03 +0100 Bertrand Jacquin > >> > <bertr...@jacquin.bzh> said: Hey, On 31/03/2015 15:51, Stefan Schmidt > >> > wrote: o Talk to beber to remove the old trac webservice to make sure we > >> > have less outdated information [assigned: Stefan] Do you want me to drop > >> > trac.e.org ? Do you want the content of trac.e.org be moved to phab (That > >> > is pain is the ass to do) ? Or to drop phab content already migrated from > >> > trac ? just drop it. :) no one is referring to the old content anymore :) > >> > and chances are the vast majority is out of date by now. trac is dead, > >> > long life to phabricator and while we are discussing web things... i've > >> > been messing with replacing our www custom php with a standard > >> wiki that ... works for us. i've tried a LOT of them. a LOT. i finally > >> found one that "works": dokuwiki. https://www.dokuwiki.org/faq:pageprotect > >> [2] [3 [2]] 1. it's in php (easy drop in for what we have). 2. we can keep > >> shot.php and update.php in the doku tree 3. it is a plain file wiki (yay! > >> no db!) 4. it has a git back-end where the web content can be put in a > >> separate git repository! (more yay!) and wiki edits on www get committed, > >> and commits to the git repo directly get pulled in every N minutes. 5. its > >> markdown is powerful enough for what we need 6. it has code hilighting and > >> more that is decent 7. styling/templating/layout is flexible enough to > >> make e.org look good. 8. has actual users and authentication. (unlike > >> some... errm gollum) 9. doesn't seem to require any exotic php modules or > >> extensions etc. so how do you want to do this? i have prepared a new www > >> git tree (have some conflicts that will need to basically be thrown out). > >> i have a test www-content git repo in my devs git repos. i will populate > >> that at least with enough initial content to make e.org usable again and > >> then go from there. server-side this will need some config - eg like > >> giving the www a devs account with an ssh priv key so the www server can > >> commit to this www-content repo... i'd just actually give the http user on > >> e.org all of that (and if it is ever abused/compromised we can nuke key > >> access and revert any changes from that user). You might want to consider > >> a dedicated git user for the wiki pages. There will come a day when you > >> want to prevent or tightly control changes to some pages. API docs and > >> other generated content come to mind. If the wiki pages are owned by > >> someone other than httpd, you just take away the write rights at the file > >> system level and it's done. https://www.dokuwiki.org/faq:pageprotect [2] > >> [3 [2]]Also, separation of concerns, traceability, damage control, blah > >> blah. any comments/input? I really like this direction. Anything that will > >> lower the barrier for new doc contributors can only help. How do you see > >> API docs fitting in? I ask because since this thread > >> <http://sourceforge.net/p/enlightenment/mailman/enlightenment-devel/thread/20141106160926.7238256c99509771c763be2b%40rasterman.com/#msg33009169 > >> [3][4]>I've been looking at how other large projects handle docs and > >> thinking about applying those ideas to e. I am moving in the direction of > >> creating doc source files as Docbook XML and then generating whatever is > >> needed from there. Some of the best projects I've looked at do it that way > >> (PHP, FreeBSD) and I'm shamelessly stealing ideas from them. -- > >> ------------- Codito, ergo sum - "I code, therefore I am" -------------- > >> The Rasterman (Carsten Haitzler) ras...@rasterman.com > >> ------------------------------------------------------------------------------ > >> Dive into the World of Parallel Programming The Go Parallel Website, > >> sponsored by Intel and developed in partnership with Slashdot Media, is > >> your hub for all things parallel software development, from weekly thought > >> leadership blogs to news, videos, case studies, tutorials and more. Take a > >> look and join the conversation now. http://goparallel.sourceforge.net/ [4] > >> [1 [4]] _______________________________________________ enlightenment-devel > >> mailing list enlightenment-devel@lists.sourceforge.net > >> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel [5] [2 > >> [5]] Links: ------ [1] http://goparallel.sourceforge.net/ [4] [2] > >> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel [5] [3] > >> https://www.dokuwiki.org/faq:pageprotect [2] [4] > >> http://sourceforge.net/p/enlightenment/mailman/enlightenment-devel/thread/20141106160926.7238256c99509771c763be2b%40rasterman.com/#msg33009169 > >> [3] > >> ------------------------------------------------------------------------------ > >> Dive into the World of Parallel Programming The Go Parallel Website, > >> sponsored by Intel and developed in partnership with Slashdot Media, is > >> your hub for all things parallel software development, from weekly thought > >> leadership blogs to news, videos, case studies, tutorials and more. Take a > >> look and join the conversation now. http://goparallel.sourceforge.net/ [4] > >> _______________________________________________ enlightenment-devel mailing > >> list enlightenment-devel@lists.sourceforge.net > >> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel [5] > >> > >> Links: > >> ------ > >> [1] http://www.stack.nl/~dimitri/doxygen/ > >> [2] https://www.dokuwiki.org/faq:pageprotect > >> [3] > >> http://sourceforge.net/p/enlightenment/mailman/enlightenment-devel/thread/20141106160926.7238256c99509771c763be2b%40rasterman.com/#msg33009169 > >> [4] http://goparallel.sourceforge.net/ > >> [5] https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > >> ------------------------------------------------------------------------------ > >> Dive into the World of Parallel Programming The Go Parallel Website, > >> sponsored by Intel and developed in partnership with Slashdot Media, is > >> your hub for all things parallel software development, from weekly thought > >> leadership blogs to news, videos, case studies, tutorials and more. Take a > >> look and join the conversation now. http://goparallel.sourceforge.net/ > >> _______________________________________________ > >> enlightenment-devel mailing list > >> enlightenment-devel@lists.sourceforge.net > >> https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > >> > > > > > > -- > > ------------- Codito, ergo sum - "I code, therefore I am" -------------- > > The Rasterman (Carsten Haitzler) ras...@rasterman.com > > > > > > ------------------------------------------------------------------------------ > > Dive into the World of Parallel Programming The Go Parallel Website, > > sponsored by Intel and developed in partnership with Slashdot Media, is > > your hub for all things parallel software development, from weekly thought > > leadership blogs to news, videos, case studies, tutorials and more. Take a > > look and join the conversation now. http://goparallel.sourceforge.net/ > > _______________________________________________ > > enlightenment-devel mailing list > > enlightenment-devel@lists.sourceforge.net > > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > > ------------------------------------------------------------------------------ > Dive into the World of Parallel Programming The Go Parallel Website, sponsored > by Intel and developed in partnership with Slashdot Media, is your hub for all > things parallel software development, from weekly thought leadership blogs to > news, videos, case studies, tutorials and more. Take a look and join the > conversation now. http://goparallel.sourceforge.net/ > _______________________________________________ > enlightenment-devel mailing list > enlightenment-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/enlightenment-devel > -- ------------- Codito, ergo sum - "I code, therefore I am" -------------- The Rasterman (Carsten Haitzler) ras...@rasterman.com ------------------------------------------------------------------------------ Dive into the World of Parallel Programming The Go Parallel Website, sponsored by Intel and developed in partnership with Slashdot Media, is your hub for all things parallel software development, from weekly thought leadership blogs to news, videos, case studies, tutorials and more. Take a look and join the conversation now. http://goparallel.sourceforge.net/ _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
