[phobos] How to build the Phobos docs?

[Jonathan M Davis]

On Monday 07 February 2011 04:58:28 Jonathan M Davis wrote:
> On Monday 07 February 2011 04:25:49 Lars Tandle Kyllingstad wrote:
> > On Mon, 2011-02-07 at 04:13 -0800, Jonathan M Davis wrote:
> > > On Thursday 03 February 2011 23:12:53 Jonathan M Davis wrote:
> > > > On Thursday 03 February 2011 11:28:47 Andrei Alexandrescu wrote:
> > > > > I looked into this and I don't know what the best way is.
> > > > > 
> > > > > Essentially it makes little sense to build Phobos without having
> > > > > the site around. Practically this is because std.ddoc is in the
> > > > > d-programming-language.org repository (as I think it should).
> > > > > 
> > > > > If you have this structure:
> > > > > 
> > > > > somedir/
> > > > > 
> > > > >    phobos/
> > > > >    d-programming-language.org/
> > > > > 
> > > > > it all works automatically. If you have d-programming-language.org
> > > > > elsewhere, do this:
> > > > > 
> > > > > make html DOCSRC=/path/to/d-programming-language.org
> > > > > 
> > > > > Suggestions for improving this are welcome.
> > > > 
> > > > Okay. I'm just totally confused now. make -f posix.mak html in Phobos
> > > > just plain doesn't work. It always gives this error:
> > > > 
> > > > make: *** No rule to make target
> > > > `../web/phobos-prerelease/phobos.html', needed by `html'.  Stop.
> > > > 
> > > > It's looking for ../web, which doesn't exist. If I run make -f
> > > > linux.mak in d- programming-language.org, then ../web gets created,
> > > > but there's still no phobos.html file, and telling Phobos to make
> > > > html still fails. And it's not like d-programming-language.org went
> > > > and created all of Phobos' html files either.
> > > > ../web-phobos-prerelease/ is completely empty.
> > > > 
> > > > So, I really don't know what I'm supposed to do to build the docs. I
> > > > was pretty much expecting make -f posix.mak html in phobos to work
> > > > (which it used to) - even if it required
> > > > ../d-programming-language.org to be there. But it doesn't work, and
> > > > I don't know what to do. Either I'm totally misunderstanding
> > > > something here, or you have something on your machine which isn't in
> > > > the repositories.
> > > 
> > > Any update or clarification on this? I'd really like to be able to
> > > build the phobos docs. It's a lot harder to edit documentation and
> > > verify how it looks when building the documentation doesn't work.
> > 
> > Here's a workaround, assuming the directory structure suggested by
> > 
> > Andrei:
> >   cd d-programming-language.org
> >   make -f linux.mak
> >   cd ..
> >   mkdir web/phobos-prerelease
> >   touch web/phobos-prerelease/phobos.html
> >   cd phobos
> >   make -f posix.mak html
> 
> That does work. Thanks. Though I do think that this needs to be fixed so
> that a fresh fork of d-programing-language.org, phobos, and druntime can
> produce the documentation with just their makefiles and without needing to
> create extra directories or empty files.
> 
> By the way, I noticed that @property shows up almost not at all in the
> documentation when I build it that way. The same goes for the docs on
> www.d- programming-language.org (which presumably generated in pretty much
> the same manner). So, it looks like the changes to std.ddoc and/or
> whatever else affects the look of the documentation has resulted in some
> stuff not showing up. I don't know what else has been affected, but
> @property certainly has.

Ah. It appears that the missing @property problem is a long-standing issue that 
I forgot about.

However, I've noticed that the tables all seem to be doubling up so that the 
same data is displayed twice. e.g. opCmp:

Returns:
  this < rhs  < 0
  this == rhs  0
  this > rhs  > 0
  this < rhs  < 0
  this == rhs  0
  this > rhs  > 0

_That_ must have something with the current std.ddoc or the css file though, 
since it doesn't happen when you generate the documentation without them.

- Jonathan M Davis