www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - dub and ddox

reply "Kelet" <kelethunter gmail.com> writes:
Hello,

I'm working on a library, and I'm trying to write the 
documentation with Sönke's ddox software[1]. As I understand, it 
works with the Ddoc documentation format[2].

The first problem I came across is that documented unit tests 
weren't being converted into examples like in [2]. I came to 
realize that you have to specifically enable it in package.json, 
like so:
"-ddoxFilterArgs": [ "--unittest-examples" ]

Now my problem is styling it. While it looks decent, it is just 
plain white. I noticed there were some questions about styling it 
before, but I mainly want it so that if I type
`dub build --build=ddox`
it will generate my styled documentation. Or at least some 
process similar to this.

I think bootDoc[3] looks pretty good out of the box, but I don't 
think it works with ddox.

I'd like to hear any other misc. comments about using ddox 
(particularly with dub). I was hoping there would be a few 
alternative styles already made under a nice license that I could 
tweak.

[1]: https://github.com/rejectedsoftware/ddox
[2]: http://dlang.org/ddoc.html
[3]: https://github.com/JakobOvrum/bootDoc
Jan 07 2014
next sibling parent reply "Kelet" <kelethunter gmail.com> writes:
Also, I cannot find any documentation on ddox arguments
(ddoxFilterArgs). Is this currently not available? I had to look
through the source code and vibe.d to figure them out.

Regards,
Kelet
Jan 07 2014
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig+dforum outerproduct.org> writes:
Am 07.01.2014 21:15, schrieb Kelet:

 Also, I cannot find any documentation on ddox arguments
 (ddoxFilterArgs). Is this currently not available? I had to look
 through the source code and vibe.d to figure them out.

 Regards,
 Kelet


Running just "ddox filter" or "dub run ddox -- filter" will print the 
available commands. I'll mention this in the documentation.
Jan 08 2014
prev sibling parent reply =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig+dforum outerproduct.org> writes:
Am 07.01.2014 21:14, schrieb Kelet:

 Hello,

 I'm working on a library, and I'm trying to write the documentation with
 Sönke's ddox software[1]. As I understand, it works with the Ddoc
 documentation format[2].

 The first problem I came across is that documented unit tests weren't
 being converted into examples like in [2]. I came to realize that you
 have to specifically enable it in package.json, like so:
 "-ddoxFilterArgs": [ "--unittest-examples" ]

 Now my problem is styling it. While it looks decent, it is just plain
 white. I noticed there were some questions about styling it before, but
 I mainly want it so that if I type
 `dub build --build=ddox`
 it will generate my styled documentation. Or at least some process
 similar to this.


In that particular case (dub build --build=ddox), you can just have your 
own versions of the style files in your docs/styles/ folder (copy and 
modify from ddox/public/styles). That won't work for "dub run 
--build=ddox" as it will always use DDOX own resources. However, for DUB 
0.9.22 I'm going to make documentation generation an own command instead 
of just a build type and add more possibilities for customization.


 I think bootDoc[3] looks pretty good out of the box, but I don't think
 it works with ddox.

 I'd like to hear any other misc. comments about using ddox (particularly
 with dub). I was hoping there would be a few alternative styles already
 made under a nice license that I could tweak.


I don't know of any meant for reuse, but since the structure of the 
generated HTML is quite simple, adapting the bootDoc style should be 
relatively straight forward.


 [1]: https://github.com/rejectedsoftware/ddox
 [2]: http://dlang.org/ddoc.html
 [3]: https://github.com/JakobOvrum/bootDoc
Jan 08 2014
parent reply "Kelet" <kelethunter gmail.com> writes:
On Wednesday, 8 January 2014 at 09:47:03 UTC, Sönke Ludwig wrote:

 In that particular case (dub build --build=ddox), you can just 
 have your own versions of the style files in your docs/styles/ 
 folder (copy and modify from ddox/public/styles). That won't 
 work for "dub run --build=ddox" as it will always use DDOX own 
 resources. However, for DUB 0.9.22 I'm going to make 
 documentation generation an own command instead of just a build 
 type and add more possibilities for customization.


The problem is that `dub build --build=ddox` overwrites ddox.css 
in docs/styles every time I run it.
Jan 08 2014
parent =?UTF-8?B?U8O2bmtlIEx1ZHdpZw==?= <sludwig+dforum outerproduct.org> writes:
Am 08.01.2014 16:34, schrieb Kelet:

 On Wednesday, 8 January 2014 at 09:47:03 UTC, Sönke Ludwig wrote:

 In that particular case (dub build --build=ddox), you can just have
 your own versions of the style files in your docs/styles/ folder (copy
 and modify from ddox/public/styles). That won't work for "dub run
 --build=ddox" as it will always use DDOX own resources. However, for
 DUB 0.9.22 I'm going to make documentation generation an own command
 instead of just a build type and add more possibilities for
 customization.


 The problem is that `dub build --build=ddox` overwrites ddox.css in
 docs/styles every time I run it.


Is that on Windows or Linux? I've just seen that on Linux it uses "cp 
-r" to copy the resources, while it should use "cp -ru" (fixed on GIT 
master). Even that is still not ideal, but the question is which is the 
best compromise:

1. Require the user to copy resources (most will probably not know and
    it's additional effort)
2. Update if newer - gets the latest updates, but may also discard
    customizations
3. Copy if not already existing - least intrusive, but doesn't get
    updated resources
4. Ask the user, may be annoying and bad for scripts

My current idea is to choose one of these as the default (probably 2 or 
3) and provide command line switches to use one of the others. But that 
will only be possible once documentation generation uses an own command 
à la "dub docs --generate --no-resources".
Jan 10 2014