How do I use DDoc?

[Jonathan M Davis]

On Saturday, November 12, 2011 13:39:21 Caligo wrote:
> On Sat, Nov 12, 2011 at 1:59 AM, Jonathan M Davis 
<jmdavisProg at gmx.com>wrote:
> > On Saturday, November 12, 2011 01:54:48 Caligo wrote:
> > > I'm about to go to bed and I can't keep my eyes open, so sorry if
> > > the
> > > answer to this is obvious.
> > > 
> > > I cloned '
> > > https://github.com/D-Programming-Language/d-programming-language.org
> > > '
> > 
> > and I
> > 
> > > want to work on documentation.  I've read
> > > http://www.digitalmars.com/d/2.0/ddoc.html, but maybe I've missed
> > > it.
> > > 
> > > 1. How do I get dmd to generate the HTML files from all those *.dd
> > > files? I run 'dmd -Dddocdir *.dd' and it creates 'docdir' folder
> > > with bunch of HTML files, but they are only a few KBs with no
> > > content.  What am I doing wrong?
> > > 
> > > 2. What are the *.ddco for?  Do they contain the predefined macros? 
> > > If
> > 
> > so,
> > 
> > > why are some of them missing than what's listed on that page?
> > 
> > If you want to build d-programming-language.org, then use its makefile.
> > 
> > make -f linux.mak
> > 
> > or
> > 
> > make -f win32.mak
> > 
> > The generated files end up in ../web/, with the current HTML
> > documentation in
> > ../web/phobos-prerelease IIRC. You have to have the Phobos and druntime
> > repositories as well, and I believe that they have to be in the same
> > directory
> > with the directory for d-programming-language.org.
> > 
> > - Jonathan M Davis
> 
> First I had to modify 'linux.mak' because I don't have a standard install
> of DMD (DMD=/path/to/dmd/dmd2/linux/bin64/dmd).
> 
> I then ran:
> 
> make -f linux.mak
> 
> and it generates ../web directory with all the HTML files from all the *.dd
> files. Plus, it gave bunch of errors and quit.  So, then I cloned Phobos
> and druntime and put them in the same directory as
> d-programming-language.org directory.  That didn't work because it seems
> that it tries to actually compile Phobos, but right now the latest Phobos
> doesn't compile, and it fails and gives errors.
> 
> So, I used the source that comes with the standard DMD release, and yes,
> they have to be in the same directory as d-programming-language.org.  That
> finally worked.

If you're building the Phobos and/or druntime from github (which building d-
programming-language.org does because it has to to generate the docs), then 
there's a decent chance that you're going to need the dmd from github as well. 
All in all, I think that building the documentation is a bit of a pain, and 
everything has to be laid out in the right place for it to work, so it's easy 
to mess up. I wish that the situation were better, but it _is_ better than it 
used to be.

- Jonathan M Davis