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?

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.

-Steve

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.
>
> -Steve

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.

Thanks for getting my noggin joggin'!

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

On Monday, 21 May 2018 at 12:37:36 UTC, Jonathan M. Wilbur wrote:
> $(DCOMPILER) -o- -op -d -Df$@ $<

That should work. It's roughly how the dlang.org documentation is built.

> 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.

Why would it need other source files? Are you missing include paths (-I switches)?

Could you post a complete example demonstrating the problem?

On Monday, 21 May 2018 at 12:37:36 UTC, Jonathan M. Wilbur wrote:
> 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?

There exist D documentation generators which attempt to only parse DDoc comments out of D source code. One is Adam's http://dpldocs.info/.