www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - revamped candydoc

reply "Dan" <dbdavidson yahoo.com> writes:
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
Oct 11 2012
next sibling parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
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
Oct 11 2012
next sibling parent reply "Dan" <dbdavidson yahoo.com> writes:
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
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
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.
Oct 11 2012
parent reply "Dan" <dbdavidson yahoo.com> writes:
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?
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
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.
Oct 11 2012
next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
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. :-)
Oct 11 2012
next sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
On Fri, 12 Oct 2012 08:16:54 +0200, Jacob Carlborg <doob me.com> wrote:


 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.


Yeah, no disagreement there. It's working fine thanks to the awesome work  
SiegeLord put into porting it to D2. I'll definitely stay with Tango, but  
external dependencies can be quite annoying, so maybe I'll just copy the  
modules I need and leave the rest.
Oct 12 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-10-12 17:05, Aziz K. wrote:


 Yeah, no disagreement there. It's working fine thanks to the awesome
 work SiegeLord put into porting it to D2. I'll definitely stay with
 Tango, but external dependencies can be quite annoying, so maybe I'll
 just copy the modules I need and leave the rest.


Ok, fair enough.

-- 
/Jacob Carlborg
Oct 13 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
On 2012-10-11 22:16, Aziz K. wrote:

 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!


Have a look at this documentation of submodules:

http://git-scm.com/book/en/Git-Tools-Submodules

Be sure to point submodules to a public address.

-- 
/Jacob Carlborg
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
On Fri, 12 Oct 2012 08:19:23 +0200, Jacob Carlborg <doob me.com> wrote:


 Have a look at this documentation of submodules:

 http://git-scm.com/book/en/Git-Tools-Submodules

 Be sure to point submodules to a public address.


That was a good read, but unfortunately it deterred me from using  
submodules. Sounds like too much trouble for me. It's not worth the hassle  
if it requires that much care and attention. Only git can get away with  
such atrocious usability issues. lol
Oct 12 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-10-12 16:55, Aziz K. wrote:


 That was a good read, but unfortunately it deterred me from using
 submodules. Sounds like too much trouble for me. It's not worth the
 hassle if it requires that much care and attention. Only git can get
 away with such atrocious usability issues. lol


Ok, I actually never read that, I probably should have. git submodules 
are not hard to use it's not harder than any other feature of git.

What you need to do is the following:

$ cd dil
$ git submodule add git://github.com/SiegeLord/Tango-D2.git
$ git commit -a -m "Add Tango-D2 as a submodule"

Then when cloning dil use the following command:

$ git clone --recursive git://path.to/dil/repository.git

If you want to update to a the latest version of Tango do:

$ cd dil/Tango-D2
$ git pull
$ cd ..
$ git commit -a -m "Update to latest version Tango-D2"

When another user needs to update his/her clone of dil, this is the 
command to run:

$ git pull
$ git submodule update --init --recursive

It's fairly simple, not that many extra commands to run.

-- 
/Jacob Carlborg
Oct 13 2012
prev sibling parent "Dan" <dbdavidson yahoo.com> writes:
On Thursday, 11 October 2012 at 18:08:47 UTC, 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.)

 Can you join me at #dil on freenode.net? Chatting will be much 
 faster than e-mailing.


Thanks for all the answers/suggestions. Aziz helped me get set up 
with dil and it is quite nice. Just for better understanding 
though, I'd like to determine why candydoc is not working for me. 
Either my command line/setup is wrong or others using this 
successfully do not have package nesting. I think the problem is 
for every module an html file is generated without the package 
prefix in the name. This presents a problem in what is generated, 
because links inside the html refer to the package qualified 
name. For example:

tmp$ mkdir pkgouter
tmp$ mkdir pkgouter/pkg1
tmp$ mkdir pkgouter/pkg2
tmp$ echo "/** Mod foo */ module pkgouter.pkg1.foo;" > 
pkgouter/pkg1/foo.d
tmp$ echo "/** Mod foo */ module pkgouter.pkg2.foo;" > 
pkgouter/pkg2/foo.d
tmp$ git clone https://github.com/eldar/candydoc.git
Cloning into 'candydoc'...
remote: Counting objects: 145, done.
remote: Compressing objects: 100% (89/89), done.
remote: Total 145 (delta 70), reused 130 (delta 55)
Receiving objects: 100% (145/145), 117.46 KiB, done.
Resolving deltas: 100% (70/70), done.
tmp$ echo "MODULES=\$(MODULE pkgouter.pkg1.foo) \$(MODULE 
pkgouter.pkg2.foo)">candydoc/modules.ddoc
tmp$ dmd -c -D  candydoc/candy.ddoc candydoc/modules.ddoc 
pkgouter/pkg1/foo.d pkgouter/pkg2/foo.d
tmp$ ls
candydoc  foo.html  foo.o  pkgouter

Only foo.html was generated referencing pkgouter.pkg2.foo and 
pkgouter.pkg2.foo. So, if I could get the dmd to output the html 
filename as the package qualified name I think it would just work.

Thanks
Dan
Oct 12 2012
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Oct 11 2012
parent reply "Aziz K." <aziz.koeksal gmail.com> writes:
On Thu, 11 Oct 2012 21:30:11 +0200, Jacob Carlborg <doob me.com> wrote:


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


What? You don't like my soft, green colours? Shame on you! :P

Ok, I'm not happy with the style myself, but I want to concentrate on  
functionality more atm.
Oct 12 2012
parent Jacob Carlborg <doob me.com> writes:
On 2012-10-12 21:06, Aziz K. wrote:


 What? You don't like my soft, green colours? Shame on you! :P


Hehe :)


 Ok, I'm not happy with the style myself, but I want to concentrate on
 functionality more atm.


Understandable. I'm not very good with design and graphics myself so I 
probably shouldn't complain that much.

-- 
/Jacob Carlborg
Oct 13 2012
prev sibling parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
On Thursday, 11 October 2012 at 14:26:54 UTC, Dan wrote:

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


bootDoc[1] uses Twitter's Bootstrap theme for styling, and has a 
lot of extra features implemented with JavaScript. It works right 
out of the box as a git submodule and has a fair bit of 
documentation. The modules.ddoc file format is compatible with 
that of candyDoc.

[1] https://github.com/JakobOvrum/bootDoc
Oct 12 2012