Dlang org development

This page explains commonly used commands that are used while working with the dlang.org repository which among many other things is used to build the language specification and library documentation of the D programming language.

You can also check the dlang.org contribution guide for build instructions.

Fetch dlang.org

Changes to phobos documentation require that the site (which includes automatically generated phobos documentation) builds successfully. Alternatively to building the documentation locally, you can use the documentation autotester service, which will build documentation, generate a diff of the results, and add a link to your GitHub pull request.

The following will clone the dlang.org repository:

cd ~/dlang
git clone https://github.com/dlang/dlang.org
cd dlang.org

Furthermore, all of dmd, druntime, phobos, tools are needed for the site to build. The instructions below will build the site to ~/dlang/dlang.org/web.

Build new Phobos documentation

If you are just interested in previewing your change to Phobos documentation, the html and phobos-prerelease will save time:

 make -f posix.mak html phobos-prerelease

Of course, parallelizing with -j improves speed as well.

To informally test it, open the appropriate HTML documents in that directory. Note that the currently released phobos would be in ~/dlang/dlang.org/web/phobos, whereas the current (fresh) build of phobos's documentation will reside in ~/dlang/dlang.org/web/phobos-prerelease. So, for example, if you change the embedded documentation in ~/dlang/phobos/std/conv.d, the changes are visible in ~/dlang/dlang.org/web/phobos-prerelease/std_conv.html. (The build process replaces the slashes in submodules with underscores.)

Avoiding network traffic

Note that one of the first lines output during the make run looks like this:

LATEST=2.110.0 <-- place in the command line to skip network traffic.

That's advice worth heeding because fetching LATEST automatically involves network traffic, which adds time to the build. So for future builds use this:

make -f posix.mak LATEST=2.110.0 html phobos-prerelease

Full build

Note that the full build all of the documentation in all forms, including Kindle builds and various other things that may require installing additional tools, and may download/build old versions of DMD. This may take some time and can be run with:

make -f posix.mak

Or if you want to avoid network traffic:

make -f posix.mak LATEST=2.110.0