dlang.org repo is extremely annoying to work with

[H. S. Teoh]

In the old days, all I needed to do a documentation test build was to
clone dlang/dlang.org and run `make -f posix.mak html`.

These days, nothing works quite right.  Any invocation of make causes it
to download a whole bunch of irrelevant stuff like binaries for
releases, which are completely unnecessary 'cos all I want is to check
whether a doc change broke the HTML formatting or not.  This in itself
wouldn't have been so bad, if it weren't for the fact that this build
also invokes dub to build a whole bunch of stuff that *randomly* breaks
depending on the system environment and detritus left over from previous
attempts.  Like, it would randomly fail to compile something and abort
with screenfuls of linker errors.

The only way I could get it any semblance of sanity from it is to
specify DMD=/path/to/working/dmd manually, and forcefully delete my dub
cache, dlang.org/web, dlang.org/.generated, dmd/generated,
druntime/generated and phobos/generated. Then do a `make -f posix.mak
all`.  But even after this, it somtimes STILL randomly fails to build
some files.  The comment header in posix.mak claims that the `html`
target will create all static HTML files, but this is false.  I've spent
the last 2 days in hair-pulling frustration trying to get it to rebuild
dmd-linux.html, which I managed to ONCE out of like 50 tries, and right
now I don't even remember exactly what sequence of commands is required
to coax it to do this. The `html` target doesn't do it, the `docs`
target doesn't do it, not even the `all` target does it. Deleting the
old version of the file doesn't do it, nuking the generated web/
subdirectory doesn't do it either.

WHAT exactly is required to get this crock to rebuild that file???

I appreciate that the website has become more complex and that to build
parts of it we need a working D toolchain. But I seriously wish there
was a SINGLE, RELIABLE build procedure that does whatever it needs to do
in order to regenerate a specific .html file that I'm working on.
Without random breakages and undocumented external dependencies that may
or may not work depending on undocumented environment factors.  In its
current state, I'm HIGHLY tempted to just throw out the window any
contribution I may have that requires a doc change, because I have no
way to reliably test it, other than just posting the PR, flaws and all,
and waiting for CI to complain about doc formatting -- which I don't
have the patience for, the turnaround time is way too long. So much for
D being one of the languages with the fastest turnaround times...


T

-- 
The right half of the brain controls the left half of the body. This means that only left-handed people are in their right mind. -- Manoj Srivastava