DOC: add a howto page on debug builds

[rgommers]

Closes gh-461
Closes gh-207
Also xref gh-459 and gh-441 which are already closed but contain discussion relevant to debug builds.

[WillAyd]

Looks nice!

[QuLogic]

Isn't it?

Suggested change

	a debug build. To do so, we need to use the ``buildtype`` argument, which is
	a debug build. To do so, we need to use the ``buildtype=debug`` argument, which is

[rgommers]

I was calling buildtype the argument, and I'd consider debug its value. The full invocation is given on the pip install line further down.

I don't have a strong preference here - the way I have it now seems more concise to me, but it could also be buildtype=debug or -Dbuildtype=debug.

[dnicolodi]

I would write either "buildtype option" (preferred) or "-Dbuildtype=debug argument".

[rgommers]

Updated to "buildtype option"

[QuLogic]

Sorry, perhaps I was unclear; you have "the buildtype option, which is equivalent to -Ddebug=true -Doptimization=0", which is not directly exactly true. It is buildtype=debug which is equivalent to those two settings; buildtype by itself is equivalent to many combinations of those options.

[dnicolodi]

Thanks. Indeed, the sentence as it reads now is not precise. I'll fix this.

[rgommers]

Good point @QuLogic, thanks. The fix is included as part of gh-476.

[dnicolodi]

I usually prefer the impersonal form for documentation, but it may just be a professional bias, thus it is ok this way too. Otherwise I just have a couple of minor comments.

[rgommers]

I usually prefer the impersonal form for documentation

I usually prefer this form, and I also think it's fine either way. As long as individual pages are consistent so it doesn't look too messy.