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

On Wednesday, 19 January 2022 at 21:58:17 UTC, H. S. Teoh wrote:
> In the old days, all I needed to do a documentation test build…

I don’t know how to build the website locally either, but I never needed to. I have done all my edits in the browser with the “Improve this page” link. In the resulting PR I then waited for the CI to build the site, after which I could check the result without needing to leave the browser. It isn’t the quick edit-build-validate cycle that you are probably looking for, but it works every time. Might want to mark the PR as draft to prevent it from being merged before you are happy with it.

— Bastiaan.