How to build phobos docs for dlang.org

[Mark Isaacson via Digitalmars-d]

I am in the process of working on some documentation improvements
for Phobos. I am running into an issue while testing. Namely, I
do not know how to build the ddocs for Phobos in quite the way
that dlang.org does.

I can build them with: posix.mak -f DMD=TheRightOne html

But everything is poorly formatted, and more importantly, there's
some wizardry going on to make std.container look like one file
on dlang.org and I therefore cannot find out how to preview my
changes to the several files that actually compose that package.
In other words, if I go to the page for std_string.html, it works
perfectly, but if I try go to std_container.html, it does not
exist because there is no container.d file.

If I build dlang.org separately, I cannot follow the library
reference link. The makefile for dlang.org includes rules for
phobos-release and phobos-prerelease, but as far as I can tell,
this does not generate the content I need (or I am not able to
easily find it). If I copy the fully-built phobos html build into
dlang.org/web/phobos then I can see the pages with the familiar
dlang.org color scheme and layouts, but std_container.html still
does not exist, and that is my fundamental problem.

This should really be documented somewhere. If nowhere else, this
file seems appropriate:
https://github.com/D-Programming-Language/dlang.org/blob/master/CONTRIBUTING.md

I hereby volunteer to document whatever answer I am given.

[Robert burner Schadek via Digitalmars-d]

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done http://wiki.dlang.org/Building_DMD#Building_the_Docs

[Andrei Alexandrescu via Digitalmars-d]

Post by Robert burner Schadek via Digitalmars-d

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done http://wiki.dlang.org/Building_DMD#Building_the_Docs

Shall we link or copy that to CONTRIBUTING.md? -- Andrei

[Robert burner Schadek via Digitalmars-d]

On Wednesday, 1 October 2014 at 10:03:33 UTC, Andrei Alexandrescu

Post by Andrei Alexandrescu via Digitalmars-d

On Wednesday, 1 October 2014 at 06:29:46 UTC, Mark Isaacson

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done
http://wiki.dlang.org/Building_DMD#Building_the_Docs

Shall we link or copy that to CONTRIBUTING.md? -- Andrei

I will create a PR with a link to the "Building DMD" wiki right
now.

[Robert burner Schadek via Digitalmars-d]

On Wednesday, 1 October 2014 at 10:14:26 UTC, Robert burner

Post by Robert burner Schadek via Digitalmars-d

Post by Andrei Alexandrescu via Digitalmars-d
Shall we link or copy that to CONTRIBUTING.md? -- Andrei

I will create a PR with a link to the "Building DMD" wiki right
now.

https://github.com/D-Programming-Language/phobos/pull/2575

[Mark Isaacson via Digitalmars-d]

On Wednesday, 1 October 2014 at 09:00:51 UTC, Robert burner

On Wednesday, 1 October 2014 at 06:29:46 UTC, Mark Isaacson

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done
http://wiki.dlang.org/Building_DMD#Building_the_Docs

I saw this yesterday and followed the instructions but was unable
to get it to work. At a minimum, the first 'make' does not do
anything and the 'generated/linux/default' directory does not
exist. I see 'generated/linux/64' instead if I use the posix.mak
file. If I proceed using that directory instead, I end up with
the same problem: Now when I run the phobos html build it does
format everything in the dlang.org colors, but I'm still missing
std_container.html.

[Andrei Alexandrescu via Digitalmars-d]

Post by Robert burner Schadek via Digitalmars-d

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done http://wiki.dlang.org/Building_DMD#Building_the_Docs

I saw this yesterday and followed the instructions but was unable to get
it to work. At a minimum, the first 'make' does not do anything and the
'generated/linux/default' directory does not exist.

I think I fixed that a while ago; "default" was a mistake.

I see
'generated/linux/64' instead if I use the posix.mak file. If I proceed
using that directory instead, I end up with the same problem: Now when I
run the phobos html build it does format everything in the dlang.org
colors, but I'm still missing std_container.html.

I think for a while now Phobos documentation has been produced as part
of building dlang.org (which itself is right now difficult to build
without babysitting for unrelated reasons). So building Phobos docs
straight from Phobos might have some bit rot.

We should sort this out when I get back in a Facebook chat. I recommend
you start with phobos/posix.mak and build from there. Take a white box
approach - open posix.mak in an editor and see what happens when you
build "html". You'll see where the generated docs go (I think in a dir
called "web" that is configurable by choosing DOC_OUTPUT_DIR. Doing so
is easy from the outside:

make html DOC_OUTPUT_DIR=/tmp/wtf


Andrei

[H. S. Teoh via Digitalmars-d]

Post by Robert burner Schadek via Digitalmars-d

Post by Mark Isaacson via Digitalmars-d
I hereby volunteer to document whatever answer I am given.

already done http://wiki.dlang.org/Building_DMD#Building_the_Docs

I saw this yesterday and followed the instructions but was unable to
get it to work. At a minimum, the first 'make' does not do anything
and the 'generated/linux/default' directory does not exist. I see
'generated/linux/64' instead if I use the posix.mak file. If I proceed
using that directory instead, I end up with the same problem: Now when
I run the phobos html build it does format everything in the dlang.org
colors, but I'm still missing std_container.html.

Here's what I do:

cd /path/to/dlang.org
make -f posix.mak html
cp -rf web /path/to/webdir/

cd /path/to/phobos
make -f posix.mak html
cp -rf ../web /path/to/webdir/

This installs the Phobos docs in /path/to/webdir/web/phobos-prerelease/*
(note, by default it does NOT install to ../web/phobos/*). So assuming
your webserver root points to /path/to/webdir, you can then point your
browser to:

http://your.web.server/web/phobos-prerelease/std_container.html

Let me know if this still doesn't help.


T

[Mark Isaacson via Digitalmars-d]

On Wednesday, 1 October 2014 at 18:00:11 UTC, H. S. Teoh via

Post by H. S. Teoh via Digitalmars-d
cd /path/to/dlang.org
make -f posix.mak html
cp -rf web /path/to/webdir/
cd /path/to/phobos
make -f posix.mak html
cp -rf ../web /path/to/webdir/
This installs the Phobos docs in
/path/to/webdir/web/phobos-prerelease/*
(note, by default it does NOT install to ../web/phobos/*). So
assuming
your webserver root points to /path/to/webdir, you can then
point your
http://your.web.server/web/phobos-prerelease/std_container.html
Let me know if this still doesn't help.
T

Still no dice. I'll hop on messenger with Andrei and see if we
can't resolve it.