www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Sections in Ddoc?

reply Philippe Sigaud <philippe.sigaud gmail.com> writes:
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
Aug 01 2010
parent reply Lutger <lutger.blijdestijn gmail.com> writes:
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.
Aug 02 2010
parent Philippe Sigaud <philippe.sigaud gmail.com> writes:
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
Aug 02 2010