Hi,

as per Nick's advice, I was reading on Goldie's GenDocs template documentation system:

http://www.semitwist.com/goldiedocs/v0.3/Docs/Tools/GenDocs/TemplateFormat/

That's a nice work, and I saw there something I'd like to do with Ddocs: sections. As in, document sections.

Ideally there are some modules I'd like to document that way:


Module Name

some general documentation on the module, what its use is supposed to be, the things to do, etc. Imagine an algorithm module, for example.

Section #1 - Sorting.
general documentation on the section, a specific part of the module. Say, sorting.

functions documentation for section 1.

Section #2 - Finding.
another subject there, say finding elements in a range... General explanations on the modules assumptions, trade-off, etc.

functions documentation for section 2.

an so on...

But I cannot do that with DDocs. Or can I?
Does anyone know a way to do this?

(ideally, I'd also like a summary-like part, like in Wikipedia :) )

Philippe

Philippe Sigaud wrote:

> Hi,
> 
> as per Nick's advice, I was reading on Goldie's GenDocs template documentation system:
> 
> http://www.semitwist.com/goldiedocs/v0.3/Docs/Tools/GenDocs/TemplateFormat/
> 
> That's a nice work, and I saw there something I'd like to do with Ddocs: sections. As in, document sections.
> 
> Ideally there are some modules I'd like to document that way:
> 
> 
> Module Name
> 
> some general documentation on the module, what its use is supposed to be, the things to do, etc. Imagine an algorithm module, for example.
> 
> Section #1 - Sorting.
> general documentation on the section, a specific part of the module. Say,
> sorting.
> 
> functions documentation for section 1.
> 
> Section #2 - Finding.
> another subject there, say finding elements in a range... General explanations
> on the modules assumptions, trade-off, etc.
> 
> functions documentation for section 2.
> 
> an so on...
> 
> But I cannot do that with DDocs. Or can I?
> Does anyone know a way to do this?
> 
> (ideally, I'd also like a summary-like part, like in Wikipedia :) )
> 
> Philippe

It isn't supported out of the box. You could further process ddoc output, I had something working nicely by spitting out xml instead of html and then using xquery to generate the docs, but am too much pressed for time to finish it.

A more lightweight approach is to insert a css class though a custom ddoc macro:

API_GROUP = <span class="$0"/>

From there you can use css selectors for styling. I'm not sure how far you can get with just css. A wee bit of jquery might help. It will be pretty awkard anyway I suppose.

On Mon, Aug 2, 2010 at 09:18, Lutger <lutger.blijdestijn@gmail.com> wrote:

>
> It isn't supported out of the box. You could further process ddoc output, I
> had
> something working nicely by spitting out xml instead of html and then using
> xquery to generate the docs, but am too much pressed for time to finish it.
>
> A more lightweight approach is to insert a css class though a custom ddoc macro:
>
> API_GROUP = <span class="$0"/>
>
> From there you can use css selectors for styling. I'm not sure how far you
> can
> get with just css. A wee bit of jquery might help. It will be pretty awkard
> anyway I suppose.
>

OK, thanks. I'll admit it readily: I've barely touched css, and I don't have the faintest idea what a selector is, nor how to use jquery. So I'll write it down as something that you cannot do easily and hope for brighter tomorrows.

Philippe