www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - How to build phobos docs for dlang.org

reply "Mark Isaacson" <turck11 hotmail.com> writes:
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.
Sep 30 2014
parent reply "Robert burner Schadek" <rburners gmail.com> writes:
On Wednesday, 1 October 2014 at 06:29:46 UTC, Mark Isaacson wrote:


 I hereby volunteer to document whatever answer I am given.


already done http://wiki.dlang.org/Building_DMD#Building_the_Docs
Oct 01 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 10/1/14, 2:00 AM, Robert burner Schadek wrote:

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


 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
Oct 01 2014
parent reply "Robert burner Schadek" <rburners gmail.com> writes:
On Wednesday, 1 October 2014 at 10:03:33 UTC, Andrei Alexandrescu 
wrote:

 On 10/1/14, 2:00 AM, Robert burner Schadek wrote:

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


 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.
Oct 01 2014
parent "Robert burner Schadek" <rburners gmail.com> writes:
On Wednesday, 1 October 2014 at 10:14:26 UTC, Robert burner 
Schadek wrote:

 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
Oct 01 2014
prev sibling parent reply "Mark Isaacson" <turck11 hotmail.com> writes:
On Wednesday, 1 October 2014 at 09:00:51 UTC, Robert burner 
Schadek wrote:

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


 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.
Oct 01 2014
next sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 10/1/14, 10:11 AM, Mark Isaacson wrote:

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

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


 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
Oct 01 2014
prev sibling parent reply "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
On Wed, Oct 01, 2014 at 05:11:47PM +0000, Mark Isaacson via Digitalmars-d wrote:

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

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


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

-- 
There are three kinds of people in the world: those who can count, and those
who can't.
Oct 01 2014
parent "Mark Isaacson" <turck11 hotmail.com> writes:
On Wednesday, 1 October 2014 at 18:00:11 UTC, H. S. Teoh via 
Digitalmars-d wrote:

 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


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