www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - What do you use to generate documentation?

reply "Andrea Fontana" <nospam example.com> writes:
I've tried to build documentation using ddoc format and dmd.

dmd -c -D -o- ...

Generated documentation looks ugly and without stylesheet. Am I 
wrong? I expected a phobos-like documentation.

So, what do you use to generate your D docs? Doxygen or something 
else?
Mar 13 2013
next sibling parent reply "simendsjo" <simendsjo gmail.com> writes:
On Wednesday, 13 March 2013 at 09:35:18 UTC, Andrea Fontana wrote:

 I've tried to build documentation using ddoc format and dmd.

 dmd -c -D -o- ...

 Generated documentation looks ugly and without stylesheet. Am I 
 wrong? I expected a phobos-like documentation.

 So, what do you use to generate your D docs? Doxygen or 
 something else?


Ref: http://dlang.org/ddoc.html
You can redefine the DDOC macro to use a stylesheet. Add your 
base ddoc file on the command line with redefined and additional 
macros.

Take a look at ddox and candydoc too.
http://www.dsource.org/projects/helix/wiki/CandyDoc
https://github.com/jacob-carlborg/candydoc
https://github.com/eldar/candydoc
https://github.com/rejectedsoftware/ddox

Not sure which candydoc repo is most up-to-date.
Mar 13 2013
parent reply "Andrea Fontana" <nospam example.com> writes:
On Wednesday, 13 March 2013 at 10:11:51 UTC, simendsjo wrote:

 You can redefine the DDOC macro to use a stylesheet. Add your 
 base ddoc file on the command line with redefined and 
 additional macros.


Is phobos doc based on some .ddoc file then? I see there's a 
number of .ddoc file in github d-programming-language repository 
but downloading them and adding to command line does nothing. Doc 
appears still without style...
Mar 13 2013
next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, March 13, 2013 11:59:52 Andrea Fontana wrote:

 On Wednesday, 13 March 2013 at 10:11:51 UTC, simendsjo wrote:

 You can redefine the DDOC macro to use a stylesheet. Add your
 base ddoc file on the command line with redefined and
 additional macros.


 
 Is phobos doc based on some .ddoc file then? I see there's a
 number of .ddoc file in github d-programming-language repository
 but downloading them and adding to command line does nothing. Doc
 appears still without style...


What ddoc gives you out of the box works, but it _is_ a bit ugly as far as 
styling goes. To match what dlang.org has, you'd need to grab std.ddoc from 
the d-programming-language.org repo on github along with the css directory and 
images directories, and the css and images directories would need to be 
alongside the generated html. std.ddoc handles the various macros used by 
Phobos and sets up the styling, and then the generated html pages reference 
the css and image files (so without them, you don't get the full styling).

- Jonathan M Davis
Mar 13 2013
parent reply "Andrea Fontana" <nospam example.com> writes:
On Wednesday, 13 March 2013 at 15:47:29 UTC, Jonathan M Davis 
wrote:

 On Wednesday, March 13, 2013 11:59:52 Andrea Fontana wrote:

 On Wednesday, 13 March 2013 at 10:11:51 UTC, simendsjo wrote:

 You can redefine the DDOC macro to use a stylesheet. Add your
 base ddoc file on the command line with redefined and
 additional macros.


 
 Is phobos doc based on some .ddoc file then? I see there's a
 number of .ddoc file in github d-programming-language 
 repository
 but downloading them and adding to command line does nothing. 
 Doc
 appears still without style...


 What ddoc gives you out of the box works, but it _is_ a bit 
 ugly as far as
 styling goes. To match what dlang.org has, you'd need to grab 
 std.ddoc from
 the d-programming-language.org repo on github along with the 
 css directory and
 images directories, and the css and images directories would 
 need to be
 alongside the generated html. std.ddoc handles the various 
 macros used by
 Phobos and sets up the styling, and then the generated html 
 pages reference
 the css and image files (so without them, you don't get the 
 full styling).

 - Jonathan M Davis


Is this command line correct?

dmd -D -c -o- std.ddoc *.d

It's still ugly :) Generated html doesn't contain any external 
css reference inside <head> section.
Mar 14 2013
parent reply Suliman <evermind live.ru> writes:
What do dflag: `-c do not link`. Should I pass it during the 
generation of the docs? dub is append it's automatically, but if 
I want to generate new docs every rebuild of app what is the 
reason to use this flag?
Jan 19 2017
parent reply Basile B. <b2.temp gmx.com> writes:
On Thursday, 19 January 2017 at 15:20:37 UTC, Suliman wrote:

 What do dflag: `-c do not link`. Should I pass it during the 
 generation of the docs? dub is append it's automatically, but 
 if I want to generate new docs every rebuild of app what is the 
 reason to use this flag?


Oh no 2013 !! I thought it was a hot conversation. I've been 
trapped. Why didn't you create your own subject ?
Jan 19 2017
parent reply Suliman <evermind live.ru> writes:
On Thursday, 19 January 2017 at 18:09:20 UTC, Basile B. wrote:

 On Thursday, 19 January 2017 at 15:20:37 UTC, Suliman wrote:

 What do dflag: `-c do not link`. Should I pass it during the 
 generation of the docs? dub is append it's automatically, but 
 if I want to generate new docs every rebuild of app what is 
 the reason to use this flag?


 Oh no 2013 !! I thought it was a hot conversation. I've been 
 trapped. Why didn't you create your own subject ?


It's seems that there is no any big changes in this deal.

ok. I know that there is a lot of other docs-gen, but who can 
give me answer about flag `-c` why its used?
Jan 19 2017
next sibling parent Adam D. Ruppe <destructionator gmail.com> writes:
On Thursday, 19 January 2017 at 18:45:05 UTC, Suliman wrote:

 It's seems that there is no any big changes in this deal.


I made my doc gen since then and ddox has grown since then as 
well. Only other major change is ddoc just got new styling in the 
newest dmd beta. Still the same ddoc, just nicer looking out of 
the box.


 ok. I know that there is a lot of other docs-gen, but who can 
 give me answer about flag `-c` why its used?


dmd -c means do not link the executable. You use it when just 
creating object files (for separate linking) or when you don't 
want the program generated for some other reason.

Since the command is just meant to generate docs, it used -c to 
skip generating the exe too.
Jan 19 2017
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2017-01-19 19:45, Suliman wrote:


 It's seems that there is no any big changes in this deal.


The upcoming 2.073.0 (now in release candidate) has a completely new 
default Ddoc theme.

-- 
/Jacob Carlborg
Jan 19 2017
prev sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Wed, Mar 13, 2013 at 08:47:03AM -0700, Jonathan M Davis wrote:

 On Wednesday, March 13, 2013 11:59:52 Andrea Fontana wrote:

 On Wednesday, 13 March 2013 at 10:11:51 UTC, simendsjo wrote:

 You can redefine the DDOC macro to use a stylesheet. Add your
 base ddoc file on the command line with redefined and
 additional macros.


 
 Is phobos doc based on some .ddoc file then? I see there's a
 number of .ddoc file in github d-programming-language repository
 but downloading them and adding to command line does nothing. Doc
 appears still without style...


 
 What ddoc gives you out of the box works, but it _is_ a bit ugly as
 far as styling goes. To match what dlang.org has, you'd need to grab
 std.ddoc from the d-programming-language.org repo on github along with
 the css directory and images directories, and the css and images
 directories would need to be alongside the generated html. std.ddoc
 handles the various macros used by Phobos and sets up the styling, and
 then the generated html pages reference the css and image files (so
 without them, you don't get the full styling).


[...]

If you don't want the hassle of hosting the docs on a webserver with
separate css stylesheets, etc., you could try the simple macros I wrote
for generating nicer-looking ddocs:

	https://github.com/quickfur/Viola-ddoc-macros/blob/master/viola.ddoc

It does have some hooks for customization, but right now it's just a
very rough, but OK-looking drop-in replacement for the default ddoc
output.


T

-- 
Bomb technician: If I'm running, try to keep up.
Mar 13 2013
prev sibling next sibling parent reply Basile B. <b2.temp gmx.com> writes:
On Wednesday, 13 March 2013 at 09:35:18 UTC, Andrea Fontana wrote:

 I've tried to build documentation using ddoc format and dmd.

 dmd -c -D -o- ...

 Generated documentation looks ugly and without stylesheet. Am I 
 wrong? I expected a phobos-like documentation.

 So, what do you use to generate your D docs? Doxygen or 
 something else?


I use harbored-mod (https://github.com/kiith-sa/hmod-dub). What I 
like about it:

1/ I'm not good with web things. The default styling is Okay for 
me so I don't have to lost time at writing some templates or 
others css files.
2/ I can call it in a single step from my IDE. For example after 
installing a static library, if i don't understand the API:
     - a double click to generate, using a custom tool, the doc 
using an IDE environment var that symbolize the sources files of 
the lib.
     - a double click to open the newly generated doc in the 
web-browser.

It's really a no-brainer.

Unfortunately It's not maintained anymore, but I'll go back to 
harbored the day the fork won't compile anymore.
Jan 19 2017
parent reply Nemanja Boric <4burgos gmail.com> writes:
On Thursday, 19 January 2017 at 16:47:07 UTC, Basile B. wrote:

 On Wednesday, 13 March 2013 at 09:35:18 UTC, Andrea Fontana 
 wrote:

 [...]


 I use harbored-mod (https://github.com/kiith-sa/hmod-dub). What 
 I like about it:

 1/ I'm not good with web things. The default styling is Okay 
 for me so I don't have to lost time at writing some templates 
 or others css files.
 2/ I can call it in a single step from my IDE. For example 
 after installing a static library, if i don't understand the 
 API:
     - a double click to generate, using a custom tool, the doc 
 using an IDE environment var that symbolize the sources files 
 of the lib.
     - a double click to open the newly generated doc in the 
 web-browser.

 It's really a no-brainer.

 Unfortunately It's not maintained anymore, but I'll go back to 
 harbored the day the fork won't compile anymore.


I've submitted few PRs but they never got merged. We're 
maintaining, unofficially, fork that does compile and it's 
available at: https://github.com/sociomantic-tsunami/harbored-mod
Jan 19 2017
parent Basile B. <b2.temp gmx.com> writes:
On Thursday, 19 January 2017 at 17:06:39 UTC, Nemanja Boric wrote:

 On Thursday, 19 January 2017 at 16:47:07 UTC, Basile B. wrote:

 [...]


 I've submitted few PRs but they never got merged. We're 
 maintaining, unofficially, fork that does compile and it's 
 available at: 
 https://github.com/sociomantic-tsunami/harbored-mod


Good to know !
Jan 19 2017
prev sibling parent Jacob Carlborg <doob me.com> writes:
On 2013-03-13 10:35, Andrea Fontana wrote:

 I've tried to build documentation using ddoc format and dmd.

 dmd -c -D -o- ...

 Generated documentation looks ugly and without stylesheet. Am I wrong?


Yes :). The upcoming 2.073.0 (now in release candidate) has a completely 
new default Ddoc theme.

-- 
/Jacob Carlborg
Jan 19 2017