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.


general documentation on the section, a specific part of the module. Say,
sorting.

functions documentation for section 1.


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.
 

 general documentation on the section, a specific part of the module. Say,
 sorting.
 
 functions documentation for section 1.
 

 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