On Sat, 4 Apr 2015 23:10:56 -0700 Jeff Grimshaw <jeffrey.w.grims...@gmail.com> said:
> On Thu, Apr 2, 2015 at 7:22 PM, 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. > > > This was me last year. I got about half way through trying to clean up > eina docs > before I gave up. Too much frustration and too many "Where did Doxygen put > the effing doc I just wrote?" moments. i totally get it. i've been there too. i threw my hands up in frustration and gave up. and i'm stubborn so i can only imagine how those less stubborn might react. but proof is in the pudding. no one volunteers and actually gets things done on docs. as it stands right now it's simply not working. something about how we do docs at the moment is causing this. devs don't bother because getting results from your doc efforts is like having someone pull your nails out. non-devs just can't really contribute without going throug a whole patch review process. doxy docs imho are just ugly and fixing it all takes too long (build cycles as discussed). i'm up for trying something new. it can't be worse than what we have. :) > 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. > > > > I will not defend Doxygen, because I hate it so, but the splatting and > formatting > can be fixed with different grouping and custom html/css. Many of the > problems > with the current docs are caused by Doxygen's group=page mentality and its > linking (or not) policy. but the time involved in fixing that grouping is insane... because turn-round time between "let me group like this" efforts here and there take multiple minutes to see. even > 5 seconds is too much. > > 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. > > > > 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. > > > > > Yep! :-) > > Docs should have their own tree, not mixed in with the source code. Docs > should be a first-class project and be managed that way. Devs don't write > (mostly) and writers don't dev (mostly), so just ack that fact and > create a space where the doc folks can do their work and not get in the way. that is the direction i want to try. it can't be worse than what we have. :) > I've been working (slowly) on converting things over to Docbook on my > local. When > I have something that works I will make it available on git so we have > something > to talk about. i actually wanted to look at docboook - so i quickly modded my doxyfile to make docbook docs... and doxygen refused to generate them. i spend maybe 30 mins trying to get it to do it (waiting multiple minutes between tries)... i gave up. :) i wanted to see what our docs look like in docbook and see if we can leverage that to move on from doxy. but i gave up. :) i was "not so enthused" by docbook in principle due to it being xml... (biased) :). at this point i'm kind of convinced the path is to set up a new wiki, hand-fill it with some initial content (copied over + edited/improved from our doxy docs), in order to get a handle on what the docs SHOULD look like (format/style/arrangement). mess with that until everyone is happy, then look at a larger migration of docs as well as auto-generating our new .eo world doc hierarchy. the first step of course is new wiki coming up and getting current www.e.org content there and to begin to lay out some sample base for efl (and e and others) docs. wiki first. content next. then bring up live, then docs. :) > I chose Docbook because it's a standard and other large projects use it, but > if markdown is chosen for doc source, so be it. sure - understandable. > -- Jeff Grimshaw > ------------------------------------------------------------------------------ > 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 ------------------------------------------------------------------------------ BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT Develop your own process in accordance with the BPMN 2 standard Learn Process modeling best practices with Bonita BPM through live exercises http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual- event?utm_ source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF _______________________________________________ enlightenment-devel mailing list enlightenment-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/enlightenment-devel
