October 11, 2012
Looking to get nice D documentation generation setup.
According to this, candydoc is revamped.

http://www.digitalmars.com/d/archives/digitalmars/D/announce/Revamp_of_CandyDOC_23131.html

I have vibed installed and tried to use this candydoc.

I try to follow instructions and attempt to get a bit of documentation with the following command (on linux):

dmd -v -c -D  -I.../rejectedsoftware-vibe.d-482ca76/source candydoc/modules.ddoc candydoc/candy.ddoc /.../rejectedsoftware-vibe.d-482ca76/source/vibe/data/*.d

The candydoc documentation says to list the modules in modules.ddoc, but I could not get that to do anything:
MODULES =
	$(MODULE vibe.data.bsons)
	$(MODULE vibe.data.json)
	$(MODULE vibe.data.utils)

This is why I added the *.d at the end (maybe that is required for candydoc but the readme doesn't sound like that to me).
Is this the way to do this?

The result is three html files (bson, json, utils).html, one for each module.
The symbols tab page is beautiful, but the modules page has links that
cause file not found errors. A sample missing file is: vibe.data.bsons.html
This file is indeed not created. How can I fix this?

Also, pointers to any doc generation setup with decent styling that works out of the box would be great.

Thanks,
Dan
October 11, 2012
Hi,

You might also want to check out my solution to generating documentation for D projects.
I've just run DIL on Phobos2 and uploaded the files to my Dropbox account:

http://dl.dropbox.com/u/17101773/doc/phobos2/index.html

Where else would you get a PDF of everything in Phobos2, but here (7.5MB)?:

http://dl.dropbox.com/u/17101773/doc/phobos2/Phobos.2.060.API.pdf

Packaged dev releases for your convenience:
http://dl.dropbox.com/u/17101773/next/2/index.html

-- 
My D Compiler: http://code.google.com/p/dil
October 11, 2012
On Thursday, 11 October 2012 at 15:25:37 UTC, Aziz K. wrote:
> Hi,
>
> You might also want to check out my solution to generating documentation for D projects.

Many thanks Aziz. The produced documentation is very nice! How
hard is it to set up to create that documentation. It may be
what I'm looking for if it is as simple as: include the D packages
you want documented in this config file and then run dil. If much more
complex, that is fine if there are good instructions. I'm new to
D and just want to get *simple* set up to have nice doc generation.
I know it's doable since I see nice html docs for phobos and others
all over. Unfortunately, even with the ddoc web page, I'm not sure
specifically how to get nice docs. For example, say I have two
packages with D code that have already been commented:
- /path/to/package1
- /path/to/package2
What is the shortest path to get nice html? The dlang/ddoc web page
does a great job explaining how to comment and what the macros are but
there are no dmd or rdmd command lines showing the use. If I'm not
a web/css guy and I just want reasonably nice docs, I think I just
need some existing style.ddoc file, some style sheets, and a good
command line like:
dmd -v -c -D -Dd/path/to/output/  -I/.../package1 -I/.../package2 /.../package1/*.d /.../package2/*.d

Candydoc is getting me close, but bad links are generated, so maybe I'm
using it incorrectly. So, if I'm happy with the style on this page:
http://dlang.org/phobos/index.html
and want that for my own code, is there a tutorial on how to create
it?

Thanks
Dan
October 11, 2012
It's very easy to use DIL for doc generation (at least I try hard to make it so.)

In your case you'd just have to run this command (use -I as well if required):

dil ddoc path/to/output/ package1/*.d package2/*.d -v --kandil -hl

Check out http://code.google.com/p/dil/wiki/Kandil for more info.

Let me know if you encounter any issue.
October 11, 2012
On Thursday, 11 October 2012 at 16:45:08 UTC, Aziz K. wrote:
> It's very easy to use DIL for doc generation (at least I try hard to make it so.)
>
> In your case you'd just have to run this command (use -I as well if required):
>
> dil ddoc path/to/output/ package1/*.d package2/*.d -v --kandil -hl
>
> Check out http://code.google.com/p/dil/wiki/Kandil for more info.
>
> Let me know if you encounter any issue.

Thanks again. I'm trying to build dil. It requires Tango. I downloaded and built Tango (successfully I think, because libtango-dmd.a was created). Then I run scripts/build.py, but it complains about not finding 'tango/io/stream/Format.d' not readable. I imagine my build/install of tango was incomplete, since it could not find tango. I know I need to somehow get a -I into the command so it knows where to find the tango source. I hardcoded (includes=['/path/to/Tango-D2']) into the build.py script and got to the next issue: HtmlEntities.d:2178 assert fails: Error: "bad hash function: conflicting hashes". Maybe we could take this off line if you have the patience?

October 11, 2012
I'll be happy to help you compile DIL yourself. That way I can see where my assumptions are false and my instructions are lacking and make it work for different platforms and needs. I've been considering just copying Tango's files to my src folder, because it would make compiling much easier (or going the more difficult route and automatically download/build Tango from build.py.)

Can you join me at #dil on freenode.net? Chatting will be much faster than e-mailing.
October 11, 2012
On 2012-10-11 17:01, Aziz K. wrote:
> Hi,
>
> You might also want to check out my solution to generating documentation
> for D projects.
> I've just run DIL on Phobos2 and uploaded the files to my Dropbox account:
>
> http://dl.dropbox.com/u/17101773/doc/phobos2/index.html

I liked the style that the Tango docs are using much better.

-- 
/Jacob Carlborg
October 11, 2012
On 2012-10-11 20:08, Aziz K. wrote:
> I'll be happy to help you compile DIL yourself. That way I can see where
> my assumptions are false and my instructions are lacking and make it
> work for different platforms and needs. I've been considering just
> copying Tango's files to my src folder, because it would make compiling
> much easier (or going the more difficult route and automatically
> download/build Tango from build.py.)

If you're using git you could add Tango as a submodule. I'm talking about Tango-D2 here, I heard you're porting Dil to D2. It might be possible for D1 as well using git svn.

-- 
/Jacob Carlborg
October 11, 2012
On Thu, 11 Oct 2012 21:33:15 +0200, Jacob Carlborg <doob@me.com> wrote:

> If you're using git you could add Tango as a submodule. I'm talking about Tango-D2 here, I heard you're porting Dil to D2. It might be possible for D1 as well using git svn.
>

Interesting, I didn't realize until now that you can do that with git. Is it possible to set the external git repo to a specific commit? I'll consider this option. Thanks!

I moved DIL to D2 quite a few months ago. Tango2 is still needed, mainly because some parts are essential and I want to save the time it takes porting everything to Phobos2. :-)
October 12, 2012
On 2012-10-11 22:16, Aziz K. wrote:

> Interesting, I didn't realize until now that you can do that with git.
> Is it possible to set the external git repo to a specific commit? I'll
> consider this option. Thanks!

That's the whole point, it's locked to a specific commit and you need to "force" update it to point to a later commit. You don't want your software to break just because a dependency decided to update its code.

> I moved DIL to D2 quite a few months ago. Tango2 is still needed, mainly
> because some parts are essential and I want to save the time it takes
> porting everything to Phobos2. :-)

Why is that? Tango is working just fine and Phobos is still missing some stuff that Tango has. Actually, I'm using both and there's nothing wrong with that. Tango is just yet another third party library.

-- 
/Jacob Carlborg
« First   ‹ Prev
1 2
Top | Discussion index | About this forum | D home