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

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.

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

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

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.