Can we automate stuff like https://issues.dlang.org/show_bug.cgi?id=15929? There are quite a few tools around, not to mention we could easily roll our own. Who'd like to take this project? Thx! -- Andrei

On Friday, 15 April 2016 at 18:25:58 UTC, Andrei Alexandrescu wrote:
> Can we automate stuff like https://issues.dlang.org/show_bug.cgi?id=15929? There are quite a few tools around, not to mention we could easily roll our own. Who'd like to take this project? Thx! -- Andrei

It's something I've been thinking about for a while.

This particular case is a DDox deficiency. The macros we use in our documentation are not meant for the URL structure that DDox uses. This incompatibility creates broken links. People have stepped up with PRs to replace them with better macros, which will work in DDox as well, so it's an area of active improvement.

chmgen reports broken internal links (for stuff that goes into the CHM, which is based on the DDoc Phobos documentation format, thus it wouldn't find the above broken DDox link). I've been planning into integrating it into the documentation tester, so that new broken internal links result in a test failure.

External links are a different issue. They can't be tested in the autotester (at least not fail the build), otherwise a site we link to going (temporarily) down means our master is broken. They would need special treatment, e.g. report them as some form of warnings but don't fail them.

On 4/15/16 5:38 PM, Vladimir Panteleev via Digitalmars-d wrote:
> On Friday, 15 April 2016 at 18:25:58 UTC, Andrei Alexandrescu wrote:
>> Can we automate stuff like https://issues.dlang.org/show_bug.cgi?id=15929? There are quite a few
>> tools around, not to mention we could easily roll our own. Who'd like to take this project? Thx!
>> -- Andrei
>
> It's something I've been thinking about for a while.
>
> This particular case is a DDox deficiency. The macros we use in our documentation are not meant for
> the URL structure that DDox uses. This incompatibility creates broken links. People have stepped up
> with PRs to replace them with better macros, which will work in DDox as well, so it's an area of
> active improvement.
>
> chmgen reports broken internal links (for stuff that goes into the CHM, which is based on the DDoc
> Phobos documentation format, thus it wouldn't find the above broken DDox link). I've been planning
> into integrating it into the documentation tester, so that new broken internal links result in a
> test failure.
>
> External links are a different issue. They can't be tested in the autotester (at least not fail the
> build), otherwise a site we link to going (temporarily) down means our master is broken. They would
> need special treatment, e.g. report them as some form of warnings but don't fail them.

You don't want the link checker checking external links directly anyway, that'd be a nice way to use the tester as an attack vector.  Instead, you could have the tester accumulate a set of external links and check them separately maybe once a day or whatever.

It'd also be a good way to detect new external links and give reviewers a chance to make sure it's a site we want to rely on being available enough.

On 04/15/2016 08:38 PM, Vladimir Panteleev wrote:
> The macros we use in our documentation are not meant for the URL
> structure that DDox uses. This incompatibility creates broken links.

Can we build ddox with specific macros? We use that technique with latex etc. -- Andrei

On 04/15/2016 08:38 PM, Vladimir Panteleev wrote:
> External links are a different issue. They can't be tested in the
> autotester (at least not fail the build), otherwise a site we link to
> going (temporarily) down means our master is broken. They would need
> special treatment, e.g. report them as some form of warnings but don't
> fail them.

If the link fails, should have a Google cache. If not, that's an error :o). -- Andrei

On Saturday, 16 April 2016 at 01:13:24 UTC, Andrei Alexandrescu wrote:
> On 04/15/2016 08:38 PM, Vladimir Panteleev wrote:
>> The macros we use in our documentation are not meant for the URL
>> structure that DDox uses. This incompatibility creates broken links.
>
> Can we build ddox with specific macros? We use that technique with latex etc. -- Andrei

Yep, and we do that:

https://github.com/dlang/dlang.org/blob/master/std-ddox.ddoc
https://github.com/dlang/dlang.org/blob/master/std-ddox-override.ddoc

Generating URLs is not always necessary with DDox, as it automatically turns fully-qualified names into links.