www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Dead link finding automation

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Apr 15 2016
parent reply Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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.
Apr 15 2016
next sibling parent Brad Roberts via Digitalmars-d <digitalmars-d puremagic.com> writes:
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.
Apr 15 2016
prev sibling next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Apr 15 2016
parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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.
Apr 15 2016
prev sibling parent Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Apr 15 2016