www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - Contributing to Phobos Documentation

reply "Craig Dillabaugh" <craig.dillabaugh gmail.com> writes:
Motivated by this thread:

http://forum.dlang.org/thread/measc3$qic$1 digitalmars.com

I was hoping to see if I could do some work on the Phobos 
documentation, but I am curious to know what the easiest way for 
someone with limited/no ddoc experience to get involved in this 
would be.  I checked the CONTRIBUTING.md file in phobos and it is 
a bit on the 'light' side.

I assume just fixing stuff in my local repo and sending PRs would 
be insufficient, as I should be 'testing' my documentation 
changes.  Is there a resource where I can learn how to generate 
the phobos documentation for phobos locally.

Second question, can I generate documentation for a single module 
rather than all of phobos each time I try to update something.

Craig
Mar 21 2015
next sibling parent reply "H. S. Teoh via Digitalmars-d-learn" <digitalmars-d-learn puremagic.com> writes:
On Sat, Mar 21, 2015 at 05:48:40PM +0000, Craig Dillabaugh via
Digitalmars-d-learn wrote:

 Motivated by this thread:
 
 http://forum.dlang.org/thread/measc3$qic$1 digitalmars.com
 
 I was hoping to see if I could do some work on the Phobos
 documentation, but I am curious to know what the easiest way for
 someone with limited/no ddoc experience to get involved in this would
 be.  I checked the CONTRIBUTING.md file in phobos and it is a bit on
 the 'light' side.
 
 I assume just fixing stuff in my local repo and sending PRs would be
 insufficient, as I should be 'testing' my documentation changes.  Is
 there a resource where I can learn how to generate the phobos
 documentation for phobos locally.


On Posix:

	git clone https://github.com/D-Programming-Language/dlang.org
	cd dlang.org
	make -f posix.mak phobos-prerelease
	cd ..
	ln -s dlang.org/web .
	cd ../phobos
	make -f posix.mak html

You should now be able to point your browser at
web/phobos-prerelease/index.html and see the generated docs.

Or copy web/* into your web folder of your local webserver and point
your browser to the appropriate URL.

Note that for this to work, the dlang.org and phobos repos must share a
common parent directory, as the makefiles currently make a lot of
assumptions about your directory layout, and may die horribly if you use
a "non-standard" layout.



 Second question, can I generate documentation for a single module
 rather than all of phobos each time I try to update something.


[...]

You could just run `make -f posix.mak html` and it should only update
those files that changed since you last ran it. (In theory, anyway. Make
is unreliable and sometimes you have to delete the generated files in
order to refresh them, but hopefully this will be rare.)


T

-- 
Customer support: the art of getting your clients to pay for your own
incompetence.
Mar 21 2015
parent "Craig Dillabaugh" <craig.dillabaugh gmail.com> writes:
On Saturday, 21 March 2015 at 21:53:00 UTC, H. S. Teoh wrote:

 On Sat, Mar 21, 2015 at 05:48:40PM +0000, Craig Dillabaugh via 
 Digitalmars-d-learn wrote:

 Motivated by this thread:
 
 http://forum.dlang.org/thread/measc3$qic$1 digitalmars.com
 
 I was hoping to see if I could do some work on the Phobos
 documentation, but I am curious to know what the easiest way 
 for
 someone with limited/no ddoc experience to get involved in 
 this would
 be.  I checked the CONTRIBUTING.md file in phobos and it is a 
 bit on
 the 'light' side.
 
 I assume just fixing stuff in my local repo and sending PRs 
 would be
 insufficient, as I should be 'testing' my documentation 
 changes.  Is
 there a resource where I can learn how to generate the phobos
 documentation for phobos locally.


 On Posix:

 	git clone https://github.com/D-Programming-Language/dlang.org
 	cd dlang.org
 	make -f posix.mak phobos-prerelease
 	cd ..
 	ln -s dlang.org/web .
 	cd ../phobos
 	make -f posix.mak html

 You should now be able to point your browser at
 web/phobos-prerelease/index.html and see the generated docs.

 Or copy web/* into your web folder of your local webserver and 
 point
 your browser to the appropriate URL.

 Note that for this to work, the dlang.org and phobos repos must 
 share a
 common parent directory, as the makefiles currently make a lot 
 of
 assumptions about your directory layout, and may die horribly 
 if you use
 a "non-standard" layout.



 Second question, can I generate documentation for a single 
 module
 rather than all of phobos each time I try to update something.


 [...]

 You could just run `make -f posix.mak html` and it should only 
 update
 those files that changed since you last ran it. (In theory, 
 anyway. Make
 is unreliable and sometimes you have to delete the generated 
 files in
 order to refresh them, but hopefully this will be rare.)


 T


Thanks very much.
Craig
Mar 21 2015
prev sibling parent reply "Tobias Pankrath" <tobias pankrath.net> writes:
On Saturday, 21 March 2015 at 17:48:41 UTC, Craig Dillabaugh 
wrote:

 Motivated by this thread:

 http://forum.dlang.org/thread/measc3$qic$1 digitalmars.com

 I was hoping to see if I could do some work on the Phobos 
 documentation, but I am curious to know what the easiest way 
 for someone with limited/no ddoc experience to get involved in 
 this would be.  I checked the CONTRIBUTING.md file in phobos 
 and it is a bit on the 'light' side.



http://wiki.dlang.org/Building_DMD
Mar 22 2015
parent "Meta" <jared771 gmail.com> writes:
On Sunday, 22 March 2015 at 09:26:51 UTC, Tobias Pankrath wrote:

 http://wiki.dlang.org/Building_DMD


Maybe I was doing it wrong, but I couldn't build the docs 
following those instructions on Windows 64-bit. What I did was:

cd tools
make -fwin32.mak

cd ..\phobos
make -fwin32.mak html
(copy the generated html folder to the dlang.org folder)

cd dlang.org
make -fwin32.mak

By default, building Phobos' html target puts the generated html 
folder several levels up, which is annoying. I tweaked the 
makefile to put html in the dlang.org folder, which you probably 
will want to do as well.
Mar 22 2015