Re: [Doxygen-develop] doxygen5

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Hi Pete,

You have lot of good ideas, so let me give you my thoughts...

On Apr 22, 2013, at 14:20 , Peter Morgan <ped...@gm...> wrote:

> Hi all,
> 
> I'm using doxygen a lot atmo. infact I been around the houses with documentation systems..
> from smart-docbook, thry to latest and worst sphinx..
> and still doxygen comes out on top..
> 
> I'm using it on these foss projects
> http://fgms.freeflightsim.org - a website and dev docs created with doxygen
> http://docs.freeflightsim.org - a spool out and interlinkof 5 projects..
> and
> http://ags-toolkit.daffodil.uk.com/ = my latest curious
> 
> Now as my background is both in web php python, js code and desktop c++ code
> 
> I think what I want to do is modify doxygen a little to make it more webiffied..
> and more automated.. even hosted..
> 
> so my needs and thoughts and questions are.. after looking at arouce are...
> 
> == Git ==
>  - can the  doxygen  start to use git as its native repos. this kinda works, svn is not really in anymore.. (a gf u kinda dating but releationship is boring.. from years ago.. before your first data with csv, and before that your straightforward ftp date ;-)

I've been experimenting with Git a bit locally and I like it, so that certainly a direction to go to in the future.
What would you chose as a hosting site? GitHub?

> 
> == Test Docs ==
> Can we create a test_docs/ directory to use as input for the stuff
> he idea here is to create a sample dorectory with the most complex styff we can make
> eg
> a main page
> a few pages of stuff
> a cladd with multiple inherit
> a spare.md file
> intermixed with namespaves in py, js, c++ et all thrown in 
> The output from this would be the test case kinda

Yes, makes sense. I've once posted this http://permalink.gmane.org/gmane.text.doxygen.devel/1127
Maybe a good starting point.

> 
> == New HTML 5 + CSS3 Output ==
> so instead of having all complex tags everywhere, we
> just spool out the html in html5 style..
> 
> This means the
> <header></header>
> <nav></nav>
> <content>
> <article></article>
> <aside></aside>
> </content>
> <nav></nav>
> <footer></footer>
> 
> And that is therefore a straightforward html5 document..
> 
> Css3 is the used to format and layout the document as required..
> Css-3 can be used to full max strength
> 

I'm worried about cross-browser compatibility. 
Not everyone is using the latest greatest browser.

> One important note here is that we want certain parts to be custom..
> eg
> The project logo could also be and url, or one aqquired wget
> The style sheet need to work as a standalone page also.. eg outside of doxy
> 
> Create a proper namespace..
> This means that one can easily customize..
> 
> I think the initial goal would be to create the test_docs and then use that output against the system sheet..
> 
> -- And Issue here is that the struct is too complex..
> -- we need to make the \ref and \page foo and "links" and \section match exactyle to a class
> eg
> \page foo My Foo PAge
> \section section_foo My Foo Section
> \subsubsection section_bar My Foo Section
> 
> style = body .page .section p {}
> style = body .page .subsubsection {}
> 
> So the selectors and structure need to ru in cocert with jquery..

Some more logical structure would be nice indeed. 
The current style had organically grown, not really designed ;-)

> 
> == Namespace ==
> We need to definately get away from classes such as "contents" etc
> This works in doxygen, but not in an mixed enviroment..
> to we need to adopt the doxygen namspace, particular in css
> eg a html with <html> style="/doxy.css">
> eg
> .doxygen p{
>   /* safe */
> }
> 
> This means that the "doxygen style sheet" can be added..
> 
> This will sork across a lot of boundaries

I never designed for mixed environments, but you are right.

> 
> ===================
> Auto Build Farm
> ===================
> We need a good autobuild part..
> This is possible with jenkins and alike..
> What we really want is the website and whole "system" etc atuo updated
> as each one of us touches the files.. 
> This is simple with jenkins, and hosting one is easy with Openshift

So far patch integration and release testing is done by me, so I haven't had a need
for continuous integration facilities. If anyone can temper with the code, this
would be needed indeed.

> 
> ==========================
> Tempalting
> ==========================
> The document structure and output of html needs to move into templating land..
> The resason for this is simple... Presentation is not part of a document structure..
> 
> In www land, which is where documentation co exists..
> Grentlee looks good and means we can use jinga templates.
> ie share the same stuff with a possible online inteface and rendering..

I've been thinking about this as well (and the layout file is a first step into this
direction). Doxygen does have many output formats, making this less trivial.
Probably the best solution is to start with a new backend (or use the XML output as input).

> 
> But this leads to the issue that grantlee uses script taags.. and QScript

and that doxygen doesn't use any recent version of Qt (only the wizard does).

> 
> Anyway..
> Those are my thoughts.. amd hacking away..
> I want the ags-toolkit to work with odxygen and my other simple page..
> But to do that, I am beter of wasting my time fixing doxygen ;-)

Agreed ;-)

Regards,
 Dimitri

P.S. Seems like your spelling checker can't keep up with your typing speed ;-)