Issues generating HTML documentation for Nuke

[kean]

Hi Mattt, this looks absolutely fantastic and I would really like to start using swift-doc in my projects. I downloaded the latest swift-doc version from master (85b5872) and tried running it against Nuke's master.

swift doc generate ~/Develop/Nuke/Sources/ --output Documentation --format html --module-name Nuke

My command line tools are set to Xcode 11.4.

It seems it got a bit confused. I think it might be because of some of the "namespaces" and typealiases.

The actual types are named ImageProcessors.GaussianBlur, etc.

Documentation.zip

[kean]

What I also noticed is that:

• It generated documentation for internal types.
• It got confused with enumerations. For example, for ImagePipeline/index.html file it added 12 enumeration cases. They all actually belong to different types, not to ImagePipeline.
• Some types appear as nested types, e.g. ImageTask.ImageContainer, when in reality they are not, they are just defined in the same file (ImageTask.swift in this case).

[mattt]

Thanks for your feedback, @kean!

Responding really quick to your first point, about the incorrect (long) type names: I was seeing the same thing with #16, but thought it was limited to Linux. I'll be really happy if I can reproduce it locally with Nuke; that'll let me troubleshoot the issue much more easily.

[mattt]

@kean, this should be fixed by #51. Can you please try running this again with the latest master?

[kean]

Thanks, @mattt! Most of the issues have been resolved.

I still observe an issue with nested types.

• There is a nested struct ImagePipeline.Configuation. In the generated documentation, all of the fields of this struct are displayed as fields of ImagePipeline itself. There are also displayed as fields of ImagePipeline.Configuation, but the in-line documentation is gone. ImagePipeline.Configuration is declared in a separate file.

Is it worth opening a separate issue?

[kean]

One more note, the HTML links in the documentation don't work if you browse it locally, which is a bit inconvenient. Jazzy on the other hand, works locally just fine.

[mattt]

@kean Thanks for following up. I'll have a full response for you soon, but I wanted to address one quick thing:

One more note, the HTML links in the documentation don't work if you browse it locally, which is a bit inconvenient.

It doesn't work if you open the html files directly, but you can make it work by running a local web server at the root of the generated directory. On macOS, the default Python distribution should provide a convenient, built-in solution:

$ python -m SimpleHTTPServer 5000 .build/documentation/

Then in another terminal window:

$ open http://localhost:5000

[kean]

Closing as the reported issue was fixed by #62. If I encounter more issues, I will report them separately.