Issue with relative links in subfolders

[twodayslate]

I installed swift-doc using brew. The --version says beta.3 even tho I think it is actually beta.4 (HEAD is now at 581af2f Bump version to 1.0.0-beta.4). It seems like the tag version didn't get the updated version.

I was trying to use swift-doc with this project

I was using the following command in the root directory:

swift-doc generate ./Sources --module-name BigNumber --output docs/ --format html

Unfortunately since all the urls were / navigation did not work locally. I tried the following:

swift-doc generate ./Sources --module-name BigNumber --output docs/ --format html --base-url ./

That worked for index.html but not for anything in any subfolder since the base-url would have to be ../ instead of just ./

[sergeishere]

Same for me 😞 1.0.0-beta.4

[mattt]

@twodayslate This is working as intended. The generated HTML files are intended to be hosted by a web server; opening the local files in Safari won't work as expected. If you want to preview them locally, you'll need to start up a web server. This article from MDN is a good write-up about how to do that.

$ cd path/to/Documentation
$ python -m SimpleHTTPServer 5000
$ open localhost:5000

All of that said, the user experience here isn't great. At the very least, this should be documented in the README. What would be even better would be if swift-doc had a serve subcommand that ran a local web server and automatically regenerated documentation when source files changed.

[twodayslate]

I still think this is incorrect behavior. In the current implementation you can't create server agnostic documentation. You will have to know if the documentation is in a subfolder or in the root folder of the server using the --base-url argument. Relative links would fix these issues.

In the linked MDN article static HTML files do not fall under or create any of the issues listed when serving local files.

[mattt]

@twodayslate Relative links have their own set of challenges and trade-offs. It would be nice to provide an option for relative vs. absolute, but there are other features that take priority at the moment. Static HTML (that is, viewing a file in Safari or another browser using the file:/// scheme instead of over HTTP) has other restrictions that limit its usefulness other than navigation.

For the purpose of generating HTML for publication on the web, I don't think the base URL setting is an unreasonable requirement. Do you have a use case in mind where this creates a problem?

[dtamiazzo]

Same here, I had to use --base-url .. to generate an offline documentation. You also need to replace all occurrences of href=".. in the root index.html with href=". if you want the initial page to link to your files properly.

This only allows to show the documentation in Chrome, Safari has a different way of dealing with relative paths.

Note this is a workaround and probably not the way the library was intended to be used, but could still come in handy to somebody.

[mattt]

@dtamiazzo That sounds like a lot of work. I think a better way would be to start a local HTTP server in the output directory. For example:

$ swift-doc generate ./Sources --module-name MyLibrary --output docs/ --format html --base-url /
$ php -S localhost:2222 -t docs/

Then, in another Terminal tab / window:

$ open http://localhost:2222

[geodesicer]

I had a similar problem in beta-6, and I patched the source files in just two places:

Helpers.swift: (lines 12-14)

public func path(for symbol: Symbol, with baseURL: String) -> String {
// return path(for: route(for: symbol), with: baseURL)
return path(for: route(for: symbol), with: baseURL) + ".html"
}

Generate.swift: (lines: 140-142)
case .html:
//filename = "($0.key)/index.html"
filename = "($0.key).html"
}

and then the generated index.html works locally with Safari/Chrome.

It now works to for easy documentation of our Package-components which are all local.

Would have been 5 minutes work to add that as a run-time option, for example "--simpleHTML" , but it probably would have broken some stuff I was ignorant of - sorry about that.

[geodesicer]

It seems "\" got edited away, Generate.swift changes should ofc be

Generate.swift: (lines: 140-142)
case .html:
//filename = "\($0.key)/index.html"
filename = "\($0.key).html"
}

Seems to happen when you paste code in. Probably code like that should be tagged as code to avoid that kind of thing ...

[geodesicer]

Of course there were another change necessary due to Extensions, which shows that one should never assume a 5 minutes fix is enough.

For the interested, change row 133 in HomePage.swift to the following

<a href="\#(path(for: route(for: $0), with: baseURL)).html">\#($0)</a>

then all references from the Home Page (index.html) works, including extensions.

Lets hope this is the last 5-minute fix for this.

[mattt]

@geodesicer Have you tried running a local server as described in #174 (comment)? I'm not really interested in an PRs that would change HTML output for the purposes of local file:/// browsing.

[geodesicer]

Just reinstalled the latest unmodified version, and started a web server. I get the "No such file or directory" which I got before I made my changes.

But I understand perfectly your viewpoint, that's why I normally never comment on changes I do on open source - its hard enough to keep my own code in order :)

I just needed the documentation, and jazzy seems out of date - and have 19 Packages to document, and no tool for doing it. After my changes I got this BIG index file and suddenly I saw all the gaps in the documentation - unfortunately :)

It have already been a big help, that's why I bothered commenting. Nice work!

[geodesicer]

@mattt I see your viewpoint much clearer now after generating my oh so meager documentation for the code. I wrote scripts generating the documentation in the projects and changed to a server-solution instead for easy distribution, thus avoiding the path problems. Thanks for the advice.