Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
On Thu, 11 Oct 2012 21:30:11 +0200, Jacob Carlborg 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.
Re: revamped candydoc
On Fri, 12 Oct 2012 08:16:54 +0200, Jacob Carlborg 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.
Re: revamped candydoc
On Fri, 12 Oct 2012 08:19:23 +0200, Jacob Carlborg 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
Re: revamped candydoc
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
Re: revamped candydoc
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
Re: revamped candydoc
On 2012-10-11 22:16, Aziz K. wrote: On Thu, 11 Oct 2012 21:33:15 +0200, Jacob Carlborg 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
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
Re: revamped candydoc
On Thu, 11 Oct 2012 21:33:15 +0200, Jacob Carlborg 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. :-)
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
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
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.
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?
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.
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
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
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
