View mode: basic / threaded / horizontal-split · Log in · Help
October 11, 2012
revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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