Generate Ddoc without compiling?

[Steven Schveighoffer]

On 5/21/18 12:59 PM, Jonathan M. Wilbur wrote:
> On Monday, 21 May 2018 at 12:53:47 UTC, Steven Schveighoffer wrote:
>> On 5/21/18 8:37 AM, Jonathan M. Wilbur wrote:
>>> I want to put in a feature request, but I want to gauge whether it is 
>>> even feasible or not, but a little background first:
>>>
>>> I am trying to create a Makefile to build the HTML documentation for 
>>> a Dlang project. I would like to be able to update a single HTML file 
>>> if the corresponding source changes, without having to recompile all 
>>> of the others. My rule looks like this:
>>>
>>> $(DCOMPILER) -o- -op -d -Df$@ $<
>>>
>>> But that does not work, because some of the compiled modules import 
>>> other modules, and the rule fails because DCOMPILER can't 
>>> intelligently pull in the other source files. I think requiring a 
>>> complete compile of all source to build the HTML documentation is a 
>>> big impediment to making D highly scalable.
>>>
>>> Having said that, I don't see why it would be technically impossible 
>>> to make DMD build the HTML (almost) without regard to the validity of 
>>> the source code. Is this possible? And moreover: *should* it be done? 
>>> Is it a bad idea?
>>>
>>>
>>
>> 1. I don't think it requires compiling all other files.
>> 2. You may want to use -c (not sure what the exact error is you are 
>> receiving)
>> 3. You may need to specify where the other includes are with -I (not 
>> sure what the exact error is you are receiving).
>>
>> I'm fairly certain D can do what you want it to do. But difficult to 
>> tell without more context/example.
> 
> So it seems that I still have to include all of the interfaces (at 
> least; source would work too), but I got it to work by adding the -I 
> operator:
> 
> html_documentation : $(htmldocs)
> $(htmldocs) : $(SRCDIR)/documentation/html/source/$(PACKAGE_SLUG)/%.html 
> : $(SRCDIR)/source/$(PACKAGE_SLUG)/%.d
>      $(DCOMPILER) -o- -op -d -I$(SRCDIR)/source 
> $(SRCDIR)/source/macros.ddoc -Df$@ $<
> 
> Since I am not producing binaries (per the "-o-" flag), I don't know if 
> it is still doing all the work of compiling and just not writing the 
> files to disk, or if it is just doing some basic lexing, but this is at 
> least acceptable.

The compiler is certainly doing something more than lexing, but it's not 
doing a full compile. For sure, the back-end shouldn't be used at all.

But I don't know what is done in terms of the more fancy features of D 
-- CTFE for example. It definitely has to instantiate templates to see 
which sections of the template have ddocs and whether they are included 
or not.

-Steve