Re: dub and ddox
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".
Re: dub and ddox
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.
Re: dub and ddox
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.
Re: dub and ddox
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
Re: dub and ddox
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
dub and ddox
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
