www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc adds filename as given on dmd command line in comment

reply simendsjo <simendsjo gmail.com> writes:
I use absolute paths in a build script, and Ddoc uses the full path in a 
comment in the generated files. This makes version control very 
difficult as all developers has to use the same location (and possibly 
operating system). Is there a way to avoid this without changing by 
build script?
Aug 08 2011
parent reply simendsjo <simendsjo gmail.com> writes:
On 08.08.2011 15:36, simendsjo wrote:

 I use absolute paths in a build script, and Ddoc uses the full path in a
 comment in the generated files. This makes version control very
 difficult as all developers has to use the same location (and possibly
 operating system). Is there a way to avoid this without changing by
 build script?


Could it instead just write the module? Or module as a filename?
pack.mod -> pack.mod
or
pack.mod -> pack/mod.d
Aug 10 2011
parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, August 10, 2011 09:13:02 simendsjo wrote:

 On 08.08.2011 15:36, simendsjo wrote:

 I use absolute paths in a build script, and Ddoc uses the full path in a
 comment in the generated files. This makes version control very
 difficult as all developers has to use the same location (and possibly
 operating system). Is there a way to avoid this without changing by
 build script?


 
 Could it instead just write the module? Or module as a filename?
 pack.mod -> pack.mod
 or
 pack.mod -> pack/mod.d


It probably could, but I don't know whether that's generally desirable or not. 
I'm afraid that I don't even know what you're talking about with regards to 
Ddoc using the full path in comments in the files anyway. However, I wouldn't 
expect generated ddoc to be in version control in the first place anymore than 
I'd expect generated binaries to be in version control, so if that's the 
problem, I'd suggest that you simply not put the generated ddoc in version 
control.

Regardless, if the current behavior is problematic for you, create an 
enhancement request for it. I suspect that it's something that pretty much no 
one has noticed - especially if it's something that's not actually visible in 
the documentation when you view it.

- Jonathan M Davis
Aug 10 2011
parent reply simendsjo <simendsjo gmail.com> writes:
On 10.08.2011 09:36, Jonathan M Davis wrote:

 On Wednesday, August 10, 2011 09:13:02 simendsjo wrote:

 On 08.08.2011 15:36, simendsjo wrote:

 I use absolute paths in a build script, and Ddoc uses the full path in a
 comment in the generated files. This makes version control very
 difficult as all developers has to use the same location (and possibly
 operating system). Is there a way to avoid this without changing by
 build script?


 Could it instead just write the module? Or module as a filename?
 pack.mod ->  pack.mod
 or
 pack.mod ->  pack/mod.d


 It probably could, but I don't know whether that's generally desirable or not.
 I'm afraid that I don't even know what you're talking about with regards to
 Ddoc using the full path in comments in the files anyway. However, I wouldn't
 expect generated ddoc to be in version control in the first place anymore than
 I'd expect generated binaries to be in version control, so if that's the
 problem, I'd suggest that you simply not put the generated ddoc in version
 control.

 Regardless, if the current behavior is problematic for you, create an
 enhancement request for it. I suspect that it's something that pretty much no
 one has noticed - especially if it's something that's not actually visible in
 the documentation when you view it.

 - Jonathan M Davis


I add the generated documentation to github pages to have the hosted 
documentation somewhere. I could of course move it somewhere else, but I 
don't see why I shouldn't put it there.

My generated ddoc:
         <!-- Generated by Ddoc from c:\d\ext\dwin\index.dd -->

std.algorithm:
     <!-- Generated by Ddoc from std/algorithm.d -->
Aug 10 2011
parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
On Wednesday, August 10, 2011 11:24:49 simendsjo wrote:

 On 10.08.2011 09:36, Jonathan M Davis wrote:

 On Wednesday, August 10, 2011 09:13:02 simendsjo wrote:

 On 08.08.2011 15:36, simendsjo wrote:

 I use absolute paths in a build script, and Ddoc uses the full path
 in a comment in the generated files. This makes version control
 very difficult as all developers has to use the same location (and
 possibly operating system). Is there a way to avoid this without
 changing by build script?


 
 Could it instead just write the module? Or module as a filename?
 pack.mod ->  pack.mod
 or
 pack.mod ->  pack/mod.d


 
 It probably could, but I don't know whether that's generally desirable
 or not. I'm afraid that I don't even know what you're talking about
 with regards to Ddoc using the full path in comments in the files
 anyway. However, I wouldn't expect generated ddoc to be in version
 control in the first place anymore than I'd expect generated binaries
 to be in version control, so if that's the problem, I'd suggest that
 you simply not put the generated ddoc in version control.
 
 Regardless, if the current behavior is problematic for you, create an
 enhancement request for it. I suspect that it's something that pretty
 much no one has noticed - especially if it's something that's not
 actually visible in the documentation when you view it.
 
 - Jonathan M Davis


 
 I add the generated documentation to github pages to have the hosted
 documentation somewhere. I could of course move it somewhere else, but I
 don't see why I shouldn't put it there.


Well, it's like a binary. It's completely regeneratable from the code, and 
it's generally just a waste of space to include it in a repo. Generally 
speaking, stuff which is completely generatable by build scripts isn't checked 
into a repository. Now, I can see why you'd want to do that with github, but 
generally, it's better to not include that sort of thing in a repo. Obviously 
it's up to you though.


 My generated ddoc:
          <!-- Generated by Ddoc from c:\d\ext\dwin\index.dd -->
 
 std.algorithm:
      <!-- Generated by Ddoc from std/algorithm.d -->


I suspect most people reading the std.algorithm documentation wouldn't even 
think that that's a path. Though honestly, I'd discourage you from having 
absolute paths in a build script. I don't believe that that's generally 
considered to be good practice. It's not particular portable and is likely to 
cause issues for anyone else who wants to build the project.

So, I'd argue that this is only an issue, because you're doing some stuff that 
many people would argue that you shouldn't be doing, but I see no reason not 
to create an enhancement request about it. It seems a bit odd to me that Ddoc 
would be sticking the path in there anyway.

- Jonathan M Davis
Aug 10 2011
parent simendsjo <simendsjo gmail.com> writes:
On 10.08.2011 11:33, Jonathan M Davis wrote:

 On Wednesday, August 10, 2011 11:24:49 simendsjo wrote:

 On 10.08.2011 09:36, Jonathan M Davis wrote:

 On Wednesday, August 10, 2011 09:13:02 simendsjo wrote:

 On 08.08.2011 15:36, simendsjo wrote:

 I use absolute paths in a build script, and Ddoc uses the full path
 in a comment in the generated files. This makes version control
 very difficult as all developers has to use the same location (and
 possibly operating system). Is there a way to avoid this without
 changing by build script?


 Could it instead just write the module? Or module as a filename?
 pack.mod ->   pack.mod
 or
 pack.mod ->   pack/mod.d


 It probably could, but I don't know whether that's generally desirable
 or not. I'm afraid that I don't even know what you're talking about
 with regards to Ddoc using the full path in comments in the files
 anyway. However, I wouldn't expect generated ddoc to be in version
 control in the first place anymore than I'd expect generated binaries
 to be in version control, so if that's the problem, I'd suggest that
 you simply not put the generated ddoc in version control.

 Regardless, if the current behavior is problematic for you, create an
 enhancement request for it. I suspect that it's something that pretty
 much no one has noticed - especially if it's something that's not
 actually visible in the documentation when you view it.

 - Jonathan M Davis


 I add the generated documentation to github pages to have the hosted
 documentation somewhere. I could of course move it somewhere else, but I
 don't see why I shouldn't put it there.


 Well, it's like a binary. It's completely regeneratable from the code, and
 it's generally just a waste of space to include it in a repo. Generally
 speaking, stuff which is completely generatable by build scripts isn't checked
 into a repository. Now, I can see why you'd want to do that with github, but
 generally, it's better to not include that sort of thing in a repo. Obviously
 it's up to you though.



To host on github pages, you have to add a branch in your project called 
gh-pages that includes the html files.
The documentation is not distributed with my main repo, and is created 
by the build script.
Blame github :)



 My generated ddoc:
           <!-- Generated by Ddoc from c:\d\ext\dwin\index.dd -->

 std.algorithm:
       <!-- Generated by Ddoc from std/algorithm.d -->


 I suspect most people reading the std.algorithm documentation wouldn't even
 think that that's a path. Though honestly, I'd discourage you from having
 absolute paths in a build script. I don't believe that that's generally
 considered to be good practice. It's not particular portable and is likely to
 cause issues for anyone else who wants to build the project.

 So, I'd argue that this is only an issue, because you're doing some stuff that
 many people would argue that you shouldn't be doing, but I see no reason not
 to create an enhancement request about it. It seems a bit odd to me that Ddoc
 would be sticking the path in there anyway.

 - Jonathan M Davis



The reason why I have the build script is because of my windows setup..
When I run system(), it doesn't automatically use build scripts cwd.
I have %HOMEDRIVE%=S: and other oddities - and to get around that, my 
cmd.exe starts in c:\temp...

I can easily change this by running system("c: && cd\<myprepopath> && 
dmd ..."), so I guess that's what I'll do.
Aug 10 2011