Windows: Incorrect paths are generated

[redmunds]

On Windows, in the Dependencies section of the brackets.js file, if I click on “Menus”, the link is to:

file:///C:/Users/redmunds/dev/github/brackets/docs/modules/command/Menus.html

but the file is actually located at:

file:///C:/Users/redmunds/dev/github/brackets/docs/modules/src/command/Menus.html

Actually, the link is:

<a href="..\../modules/command&#x2F;Menus.html">Menus</a>

The backslash () path separator will only work on a Windows system, so that should be a forward slash. Also, the /src folder is missing.

Seems like link should be one of these:

<a href="command/Menus.html">Menus</a>
<a href="../modules/command/Menus.html">Menus</a>
<a href="../../src/modules/command/Menus.html">Menus</a>

Interesting that in the left sidebar, there is another link to same module that is correct.

[jbalsas]

Hey @redmunds I've pushed a fix for this and a new version to npm registry. Can you verify this is fixed for you?

Additionally, I'm seeing that after a run, the output folder gets locked and I cannot overwrite it in subsequent runs. Since I'm running on a VM, could you confirm if this happens to you as well?

Thanks!

[redmunds]

@jbalsas No, it's still not fixed. I left this out of the original recipe, but the first thing I do in index.htmis click on "brackets" module

This is the link I see in Dependencies section for "Menus":
<a href="..\..\../modules/command/Menus.html">Menus</a>

Interesting that the "Menus" link in the left sidebar does work (although it still has backslashes that will only work on Windows):
<a href="..\..\../modules/brackets/src/command/Menus.html">Menus</a>

output folder gets locked

No, I'm not seeing that. I added a dependency to Menus.js, shutdown Brackets, and re-ran the apify command. I did not see any errors in terminal and the dependency was added when I looked at the api docs. Let me know if that's not a good test.

[jbalsas]

Hey @redmunds, I fixed the left backslashes and I think I finally figured out what's going on. Please, correct me if I'm mistaken.

My guess is that you're running the apify command with the --source parameter pointing to the whole Brackets folder instead of just src. Do you think this should be possible? As I see, we'll be documenting way more than just the sources with this (tests and other libraries, for example).

When processing a module, we only know about its dependencies by analyzing the require() calls. Chek for example brackets.js:

  FileSystem  = require("filesystem/FileSystem"),
  QuickOpen   = require("search/QuickOpen"),
  Menus       = require("command/Menus"),
  FileUtils   = require("file/FileUtils"),

Since those are relative to the src folder, the urls will break if the root folder we're using does not match.

Afaict, there's no easy way to guess the baseUrl for the require calls. If we'd want this in a generic way, we'd need to pass something resembling the require.js configuration paths, and probably create as well some kind of sandboxes in case you have more than one source folder (like src and tests).

With all these in mind, I'm not sure if it's really worth it, considering everything should be fine if you apify just your sources ;)

What do you think?

[redmunds]

I was only trying to generate docs for src folder. As taken from one of your examples I was using --source src/. But that was causing output folder to be inside brackets folder (which makes all the files show up in git), so I went up a folder and started using --source brackets/src/.

[jbalsas]

Oh, I see... that makes sense.

I think we can then just normalize all the file paths to be relative to the --source parameter. In that way, both the file paths on the left file list and the ones in the dependencies list should be fine.

I'll work on that tomorrow and let you know.

Thanks!

[redmunds]

A reasonable solution would be just to blindly replace \ with / in file/url paths on Windows.

UPDATE: I got the latest version and see this is already done.

[jbalsas]

Yep, did that part, and was working on a normalizePath method as well to make paths relative to the --source parameter, but didn't have time to finish yet

[redmunds]

Updated subject. Removed Windows label since this applies to all platforms.

UPDATE: I'm still seeing broken links on Dependencies, so I changed Subject back to original.