www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Generate Ddoc without compiling?

reply Jonathan M. Wilbur <jonathan wilbur.space> writes:
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?
May 21 2018
next sibling parent reply Steven Schveighoffer <schveiguy yahoo.com> writes:
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
May 21 2018
parent reply Jonathan M. Wilbur <jonathan wilbur.space> writes:
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'!
May 21 2018
parent Steven Schveighoffer <schveiguy yahoo.com> writes:
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
May 21 2018
prev sibling next sibling parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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?
May 21 2018
prev sibling parent Vladimir Panteleev <thecybershadow.lists gmail.com> writes:
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/.
May 21 2018