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
next sibling 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 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
prev sibling parent 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