Is there any non-insane way of changing some documentation in a module and checking that any links/xrefs you may have added actually work?

The dlang.org makefile appears to happily erase uncommitted changes in ../druntime and ../phobos. I'm really struggling for words to describe how infuriating that is. I ran make and it deleted my work in a separate folder. Not OK.

On Monday, 8 June 2015 at 11:27:58 UTC, John Colvin wrote:
> Is there any non-insane way of changing some documentation in a module and checking that any links/xrefs you may have added actually work?
>
> The dlang.org makefile appears to happily erase uncommitted changes in ../druntime and ../phobos. I'm really struggling for words to describe how infuriating that is. I ran make and it deleted my work in a separate folder. Not OK.

This shouldn't happen. Are you sure you worked in the "phobos" directory and not in some versioned one like "phobos-2.067.1"? That would be a directory created by dlang.org.

Slightly different topic, related to changing documentation without losing your sanity: When building dlang.org, changes in druntime/phobos are not properly picked up.

You can try deleting a strategic file like dlang.org/web/phobos-prerelease/index.html which should trigger a rebuild. See posix.mak for what files are dependencies to the different targets.

Or just do a fresh build every time: `make -f posix.mak clean; make -f posix.mak phobos-prerelease`.

I have an open pull request that's supposed to fix this:
https://github.com/D-Programming-Language/dlang.org/pull/993

On 6/8/15 7:27 AM, John Colvin wrote:
> Is there any non-insane way of changing some documentation in a module
> and checking that any links/xrefs you may have added actually work?
>
> The dlang.org makefile appears to happily erase uncommitted changes in
> ../druntime and ../phobos. I'm really struggling for words to describe
> how infuriating that is. I ran make and it deleted my work in a separate
> folder. Not OK.

If you just want to check that a file's content is going to show up, I use:

dmd -D -o- -c std/somemod.d

The output is not styled properly. But the output should have working links.

FWIW, I avoid building phobos docs. It's too painful. If I change dlang.org docs, I will build those, but not phobos.

-Steve

On Monday, 8 June 2015 at 13:34:14 UTC, Steven Schveighoffer wrote:
> If you just want to check that a file's content is going to show up, I use:
>
> dmd -D -o- -c std/somemod.d
>
> The output is not styled properly. But the output should have working links.
>
> FWIW, I avoid building phobos docs. It's too painful. If I change dlang.org docs, I will build those, but not phobos.
>
> -Steve

What's painful about building phobos docs? It only takes one command.

On 6/8/15 9:36 AM, Meta wrote:
> On Monday, 8 June 2015 at 13:34:14 UTC, Steven Schveighoffer wrote:
>> If you just want to check that a file's content is going to show up, I
>> use:
>>
>> dmd -D -o- -c std/somemod.d
>>
>> The output is not styled properly. But the output should have working
>> links.
>>
>> FWIW, I avoid building phobos docs. It's too painful. If I change
>> dlang.org docs, I will build those, but not phobos.
>
> What's painful about building phobos docs? It only takes one command.

Yes, after you've set up an appropriate directory structure. And that's not easy. I've done it before, a long time ago, so maybe it's gotten better. Clearly, John can tell you more ;)

-Steve

On 2015-06-08 15:34, Steven Schveighoffer wrote:

> If you just want to check that a file's content is going to show up, I use:
>
> dmd -D -o- -c std/somemod.d
>
> The output is not styled properly. But the output should have working
> links.

What about the custom ddoc macros?

-- 
/Jacob Carlborg

On 6/8/15 10:07 AM, Jacob Carlborg wrote:
> On 2015-06-08 15:34, Steven Schveighoffer wrote:
>
>> If you just want to check that a file's content is going to show up, I
>> use:
>>
>> dmd -D -o- -c std/somemod.d
>>
>> The output is not styled properly. But the output should have working
>> links.
>
> What about the custom ddoc macros?
>

Hm... I guess you could include them. I don't even know how to do that.

If the docs don't turn out the way I expect, but I think it would with a full build, I usually just stick a warning on my PR that I didn't test it :P

-Steve

On Monday, 8 June 2015 at 13:36:08 UTC, Meta wrote:
> On Monday, 8 June 2015 at 13:34:14 UTC, Steven Schveighoffer wrote:
>> If you just want to check that a file's content is going to show up, I use:
>>
>> dmd -D -o- -c std/somemod.d
>>
>> The output is not styled properly. But the output should have working links.
>>
>> FWIW, I avoid building phobos docs. It's too painful. If I change dlang.org docs, I will build those, but not phobos.
>>
>> -Steve
>
> What's painful about building phobos docs? It only takes one command.

What's _not_ painful?

Atila

On Monday, 8 June 2015 at 15:07:11 UTC, Atila Neves wrote:
> What's _not_ painful?
>
> Atila

It's painful to get set up, but once you do it's smooth sailing. It took one small edit to the makefile to allow me to build the website and the docs on Windows.

On 6/8/15 4:27 AM, John Colvin wrote:
> Is there any non-insane way of changing some documentation in a module
> and checking that any links/xrefs you may have added actually work?
>
> The dlang.org makefile appears to happily erase uncommitted changes in
> ../druntime and ../phobos. I'm really struggling for words to describe
> how infuriating that is. I ran make and it deleted my work in a separate
> folder. Not OK.

Bummer about that. I've never encountered this problem. What command(s) did you run? -- Andrei